Skip to content

Connecting a messenger (Slack, Telegram, WhatsApp, SMS, Discord) ​

Short version: the SDK ships no messenger connectors, and it should not. A chat transport is edge plumbing, not accountability, so it sits on the wrong side of the non-goal line: the formats and signing schemes churn, every platform already has a mature Go library (slack-go, telebot, discordgo, the Twilio and Meta SDKs), and none of it makes an agent more provable. What the SDK owes you is a run that is safe to drive from an untrusted, redelivering channel. That it already provides. This page shows the pattern; the runnable version is examples/webhook.

The core is transport-agnostic on purpose ​

Agent.Run(ctx, runID, input) takes a caller-supplied runID and a plain string. Session(ctx, id) gives multi-turn continuity keyed by any string without a >: the session runs its turns under <id>>@..., and > separates a sub-agent's run from its parent's (join composite ids with another separator). A messenger integration is glue you write in your own webhook handler:

  1. Verify the provider's signature and return 200 fast (both are the handler's job, not the SDK's).
  2. Map the channel's thread or conversation id to a run or a Session id.
  3. Call Run / Send, then post the reply back over the provider's API.

Nothing here is missing from the SDK. The one part worth doing deliberately is the next section.

Idempotency is the part that matters ​

Every messenger redelivers. Slack retries any event you do not acknowledge within three seconds, up to three times; Twilio, Telegram, and Meta all retry on timeout. A handler that re-runs the agent on a redelivery fires its side-effecting tools twice: a double ticket, a double refund, a double outbound message. Most frameworks make you stand up a separate dedup table to defend against this.

Here it falls out of the durable journal you already have. store.Do is at-most-once per (runID, step): a recorded step returns its result without re-running. Key the work off the provider's stable event id and a redelivery replays instead of re-executing. This is the same at-most-once property the chaos benchmark proves (maxFired=1), now applied to an inbound channel.

Stateless command bot ​

For command-style bots with no memory, key the run itself by the event id:

go
// Slack sends a stable event_id / client_msg_id; the X-Slack-Retry-Num header marks redelivery.
runID := "msg/" + channelID + "/" + eventID
res, err := a.Run(ctx, runID, agent.UserText(text))
var reply agent.Message
if res != nil {
	reply = res.Message
} // redelivery hits the same runID and replays the journal

A redelivered event resumes the recorded run rather than re-calling the model and re-firing tools.

Conversational bot ​

For multi-turn bots, use a Session keyed by the conversation/thread id for memory, and send each inbound message with SendOnce keyed by its event id. Send alone is not enough: it keys turns by index, so a redelivery would open a second turn.

go
sess, err := a.Session(ctx, conversationID)
if err != nil {
	return "", err
}
res, err := sess.SendOnce(ctx, eventID, agent.UserText(text))
if err != nil {
	return "", err // a pause/error: the redelivered event resumes the same turn
}
msg := res.Message
return msg.Text(), nil

SendOnce answers a message at most once per key. A redelivered event whose turn completed returns the recorded answer without calling the model, even if the process died after the turn and before the reply went out. A turn interrupted by a crash or a pause resumes when the event is redelivered, in its own journal, so a different message arriving in between gets its own turn; the resumed turn still sees the conversation as it stood when the turn started, since that starting point is journaled. Reusing a key for different text is ErrConfig; any key is allowed, since the turn's journal, "<conversation>>@event/<key>", carries it encoded. A conversation id may not contain >: every run a session drives is named "<id>>@...", which no run ID passed to Run can be, so a run of your own never shares a session's journal. Recover skips them (agent.IsSessionRun): an interrupted turn resumes through the session, when the event is redelivered. (agent.ResumeAgent declines a session turn's run too.) A turn's run can be cancelled like any run (agent.Cancel): Send of its message (the same text) then returns agent.ErrRunCancelled, and the next message's Send records the cancelled turn closed (with no answer, and outside the transcript) and runs its own turn; a SendOnce key whose run was cancelled stays unanswered. A saga turn's Cancel writes only its rollback request: the next message's Send drives that rollback itself and then records the turn closed. Over a store with leases it drives the rollback under the turn's lease and without holding the handle, so other callers are not blocked behind its compensators: while the rollback is in progress, any other caller gets ErrTurnContended, another worker or a second caller on the same handle alike (and the Send itself gets it if another worker is driving the turn). Over a store with no Leaser, the handle stays held across the rollback, so a second caller on the same handle waits for it. Send and SendOnce take a Message and run options, journaled with the turn's run, and return a Result. Several workers may hold handles on one conversation: every message is recorded once, and a handle that is behind catches up from the journal before answering (or before refusing a message because another message's turn looks open to it), so each new turn sees the conversation as it stands.

One worker drives a turn at a time ​

A turn's run is driven under its lease when the store implements Leaser (MemStore, store/sqlite and store/postgres do), as agent.Lease drives a run. The run loads its journal only once it holds the lease, and keeps the lease until it returns, so a worker always loads every model call an earlier worker journaled, and WithTokenBudget bounds the turn however many workers its message reaches. A second worker given the message while the first drives its turn (the redelivery SendOnce exists for, or Send of one message on two handles) does not drive it: Send or SendOnce returns at once with an error wrapping agent.ErrTurnContended, having run nothing (or, if the run has just finished and its holder has not released the lease yet, with the recorded answer). It is neither a failure nor a pause. Acknowledge the delivery and let the provider redeliver, or send the message again later: once the turn is recorded, that returns its answer without calling the model, and if the first worker stopped short (it paused, failed or died), it resumes the turn.

go
res, err := sess.SendOnce(ctx, eventID, agent.UserText(text))
var msg agent.Message
if res != nil {
	msg = res.Message
}
if errors.Is(err, agent.ErrTurnContended) {
	return "", err // another worker is answering this message: let the provider redeliver it
}
if err != nil {
	return "", err
}
return msg.Text(), nil

Name the lease and set its TTL when you open the session: a.Session(ctx, conversationID, agent.WithLeaseHolder("worker-1"), agent.WithLeaseTTL(30*time.Second)) (the defaults are a host, pid and random name, and 30 seconds). A worker that dies mid-turn holds the turn until its lease lapses, one TTL after its last renewal; a lapsed lease on a turn run is deleted by RecoverLoop's lapsed loop (Leaser.ReapLeases), since no recovery pass takes a session's run over. Over a store with no Leaser, two workers may drive one turn at once: the turn is still recorded once, but each worker counts only the spend it has seen (see Known limitations).

The first delivery runs the turn and records the reply under the event id; a redelivery returns the recorded reply without advancing the transcript. If the turn pauses (a tool needs approval) or errors, nothing is recorded, so the next redelivery correctly retries it.

Attribution for the audit trail ​

For the governed and audited story, carry the messenger user's identity into the run so the audit record ties the action to who asked. Put it in the system prompt, the tool context, or a governed input field. The run is then replayable and provable like any other, with the requester on the record. See Audit and Governance.

What stays your responsibility ​

  • Signature verification (Slack signing secret, Twilio X-Twilio-Signature, Meta app secret).
  • Acknowledging within the provider's timeout: return 200 immediately and run the agent asynchronously, keyed by the event id, so the reply is posted when ready and a redelivery replays.
  • Outbound delivery over the provider's API, including its own rate limits.
  • Mapping provider ids to your run and session ids (the two runID conventions above are a starting point, not a requirement).

Apache-2.0 licensed.