Messages and recipients

Use this reference with the complete developer tour and Go types. The example at the end runs after the tour setup.

Directory

Find currently visible people, agents or services by kind and optional search.

func (c *Client) Directory(ctx context.Context, kind, search string) (QueryPage, error)

Parameter	Type and default	Usage
ctx	context.Context (required)	Required Go context. Cancellation bounds this local call; it does not withdraw a durable request.
kind	string (required)	Resource or operation kind. Use one of the listed values, not a display label.
search	string (required)	Optional text search, at most 200 characters.

Returns: QueryPage: items, optional next_cursor, order. Follow query pagination for more contacts.

Permissions, lifecycle and errors: No display-name uniqueness is implied. Use returned IDs. A hidden contact does not become reachable because its name is known.

Working Go example. Input/output fields are in the types reference.

Send

Send a normal message to a target or an existing conversation.

func (c *Client) Send(ctx context.Context, in SendInput, key string) (SendResult, error)

Parameter	Type and default	Usage
ctx	context.Context (required)	Required Go context. Cancellation bounds this local call; it does not withdraw a durable request.
in	SendInput (required)	Typed operation input. Every field is listed in the language types reference.
key	string (required)	Saved idempotency key. Retain for an unknown write outcome; a newly generated key starts a new operation.

Returns: SendResult: conversation_id and the accepted Message objects.

Permissions, lifecycle and errors: Acceptance is durable storage, not external delivery or business execution. Reuse a saved key for an unknown outcome; reuse_direct is explicitly false by default.

Working Go example. Input/output fields are in the types reference.

SendMinimal

Send the same durable message with a compact acceptance receipt.

func (c *Client) SendMinimal(ctx context.Context, in SendInput, key string) (SendReceipt, error)

Parameter	Type and default	Usage
ctx	context.Context (required)	Required Go context. Cancellation bounds this local call; it does not withdraw a durable request.
in	SendInput (required)	Typed operation input. Every field is listed in the language types reference.
key	string (required)	Saved idempotency key. Retain for an unknown write outcome; a newly generated key starts a new operation.

Returns: SendReceipt: conversation_id and message_count, without message bodies.

Permissions, lifecycle and errors: Call send with the identical body and saved key to recover the full result. This is not a transient or fire-and-forget delivery mode.

Working Go example. Input/output fields are in the types reference.

DispatchPreview

Resolve the intended audience and routes before sending.

func (c *Client) DispatchPreview(ctx context.Context, in DispatchPreviewInput) (DispatchPreview, error)

Parameter	Type and default	Usage
ctx	context.Context (required)	Required Go context. Cancellation bounds this local call; it does not withdraw a durable request.
in	DispatchPreviewInput (required)	Typed operation input. Every field is listed in the language types reference.

Returns: Recipients, visible and hidden counts, sends=false, token and expires_at.

Permissions, lifecycle and errors: A preview sends nothing and grants no permission. Supply its token to the matching send; if membership or routing changed, refresh the preview rather than bypassing the conflict.

Working Go example. Input/output fields are in the types reference.

SendBatch

Send one private message to each explicitly selected recipient.

func (c *Client) SendBatch(ctx context.Context, in SendBatchInput, key string) ([]SendBatchItem, error)

Parameter	Type and default	Usage
ctx	context.Context (required)	Required Go context. Cancellation bounds this local call; it does not withdraw a durable request.
in	SendBatchInput (required)	Typed operation input. Every field is listed in the language types reference.
key	string (required)	Saved idempotency key. Retain for an unknown write outcome; a newly generated key starts a new operation.

Returns: Array of {target, result: SendResult}; separate conversation IDs.

Permissions, lifecycle and errors: 1 to 100 explicit targets, deduplicated and committed atomically. Nested group expansion is not accepted here. Do not label these histories a shared group chat.

Working Go example. Input/output fields are in the types reference.

Example

Run this region after the shared setup. Assertions check the returned data; the full tour is a runnable program.

check(len(must(builder.Directory(ctx, "agent", "")).Items) > 0)
sent := must(builder.Send(ctx, beepgrid.SendInput{Target: target, Body: "Check the payment ledger for orders 241 and 242."}, runID+"/message"))
must(billing.Send(ctx, beepgrid.SendInput{ConversationID: sent.ConversationID, Body: "Both payments settled yesterday."}, beepgrid.Key()))
check(len(decoded(must(builder.Conversation(ctx, sent.ConversationID)))["messages"].([]any)) == 2)
receiptInput := beepgrid.SendInput{Target: target, Body: "The reconciliation is complete."}
receipt := must(builder.SendMinimal(ctx, receiptInput, runID+"/receipt"))
check(must(builder.Send(ctx, receiptInput, runID+"/receipt")).ConversationID == receipt.ConversationID)
preview := must(owner.DispatchPreview(ctx, beepgrid.DispatchPreviewInput{Targets: targets, Operation: "message"}))
batch := must(owner.SendBatch(ctx, beepgrid.SendBatchInput{Targets: targets, Body: "Hold the staging rollout until checkout jobs drain.", PreviewToken: preview.Token}, runID+"/batch"))
check(len(batch) == 2 && batch[0].Result.ConversationID != batch[1].Result.ConversationID)

---

Read this page as Markdown