Receive mailbox messages in Chat SDK
Install @samva/chat-adapter so Chat SDK handlers receive a mailbox's email and WhatsApp messages and reply through its approval rules.
This guide connects a mailbox to Chat SDK. @samva/chat-adapter receives each email and WhatsApp
message through a signed mailbox.message.received webhook and hands it to your Chat SDK
handlers. Replies go through the mailbox's sending rules, so a rule can hold them for a person.
What you need
- A mailbox, as in Give an agent an inbox.
- A mailbox-scoped key for the agent with the approval rule
{ match: { effect: "write" }, atLeast: "person" }. See Agents and keys and Approve sends. - A webhook on that mailbox for
mailbox.message.receivedthat posts to the route you create below. See Webhooks.
Install the packages.
npm install @samva/chat-adapter chat samva @chat-adapter/state-memorySet these variables for the route.
| Variable | Value |
|---|---|
SAMVA_API_KEY | The mailbox-scoped key. |
SAMVA_MAILBOX_ID | The mailbox that receives messages. |
SAMVA_WEBHOOK_SECRET | The signing secret of the webhook. |
On Vercel, Add Samva to Vercel sets these variables for you: Samva
creates the key with the approval rule and writes SAMVA_API_KEY and SAMVA_MAILBOX_ID to your
project. Set Receive messages at to your app's /api/samva URL. The field starts with
/eve/v1/samva, the Eve route. Samva then creates the webhook and writes SAMVA_WEBHOOK_SECRET
too. If you leave the field empty, create the webhook yourself and set its secret.
To start from a working app, deploy the Next.js example. It clones the example into a new
repository and installs Samva on the new project. In the Samva step, select the new project and set
Receive messages at to its /api/samva URL.
Add the route
Create the adapter and a Chat instance, then export the POST handler that receives the webhook.
Pass the original request to the handler. Samva signs the exact body bytes, so the handler must
read the body untouched.
import { createMemoryState } from "@chat-adapter/state-memory";
import { createSamvaAdapter, receiptOf } from "@samva/chat-adapter";
import { Chat, type Message, type Thread } from "chat";
function required(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Set ${name}`);
return value;
}
const samva = createSamvaAdapter({
apiKey: required("SAMVA_API_KEY"),
mailboxId: required("SAMVA_MAILBOX_ID"),
webhookSecret: required("SAMVA_WEBHOOK_SECRET"),
});
const chat = new Chat({
userName: "Support",
adapters: { samva },
state: createMemoryState(),
concurrency: "concurrent",
});
async function acknowledge(thread: Thread, message: Message) {
if (message.author.isMe) return;
const posted = await samva.postMessage(thread.id, "Thanks for your message.");
const receipt = receiptOf(posted);
if (receipt?.state === "approvalRequired") {
console.info("Reply held for approval", receipt.actionId);
}
}
chat.onNewMention(acknowledge);
chat.onSubscribedMessage(acknowledge);
chat.onDirectMessage(acknowledge);
export const POST = (request: Request) => chat.webhooks.samva(request);Check it
Send the mailbox an email. In a test conversation, the reply returns approvalRequired, and the
held reply appears in Needs you in the dashboard. Nothing reaches the sender until a person
approves it. See Approve sends.
Held replies
postMessage returns the posted message. Pass it to receiptOf to read the receipt. A reply held
by a rule has the state approvalRequired and an actionId you can use to follow the action. A
reply no rule holds is submitted for sending.
Email threads and WhatsApp messages
Email arrives with thread scope. WhatsApp arrives as a direct message. A reply posted from a
webhook handler addresses the message that handler received, even when another message arrives
while the handler runs. A post outside a handler addresses the thread's most recent inbound
message. Set concurrency: "concurrent" on the Chat instance, as the route does, so each handler
keeps its own webhook context.
To start a conversation, call openDM(address) and post to the ID it returns. The address is an
email address or an E.164 phone number.
Parsed email text is the subject followed by the body.
Automated email
The adapter skips automated email. It checks the sender address and, when the signed webhook
includes them, the Auto-Submitted and Precedence headers. Set includeAutomatedEmail: true in
createSamvaAdapter to receive those messages.
Retries and repeated deliveries
Samva retries a webhook delivery that fails. Inside a handler, each post gets a key built from the delivery ID and the post's position in the handler, so a retry that runs the same posts in the same order does not send twice. If a retry drafts different text for a post that already exists, the adapter returns that post's saved receipt. Outside a webhook, a post with matching text to the same inbound message reuses its action.
A post to a new conversation from openDM has no such key. If its response is lost and you post
again, Samva can send it twice, so check the receipt before you retry one.
Rotate credentials
From version 0.2.0, apiKey and webhookSecret also accept a function that returns the value,
synchronously or as a promise. The adapter calls apiKey before every API request and
webhookSecret for every delivery, and caches neither, so a rotated key or secret applies at once.
If a function throws or returns an empty value, the webhook handler throws instead of answering
401, so Samva retries the delivery.
Run more than one instance
createMemoryState keeps deduplication in one process. When the route runs on more than one
instance or worker, pass a shared Chat SDK state adapter, such as Redis, so a redelivery is
handled once across all of them.
Limits
- Edits, deletes, and reactions are not supported.
- Streamed replies are buffered and submitted once they finish.
- Cards post as fallback text.
- A free-text WhatsApp reply needs an open service window, which a customer's message opens.
Next steps
- Eve and Vercel AI SDK give an agent framework the same mailbox.
- Add Samva to Vercel sets the three variables on your Vercel projects.
- The Chat SDK example is this route as a Next.js app, with a test.
@samva/chat-adapteron npm lists the published versions.