Skip to Content

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.received that posts to the route you create below. See Webhooks.

Install the packages.

npm install @samva/chat-adapter chat samva @chat-adapter/state-memory

Set these variables for the route.

VariableValue
SAMVA_API_KEYThe mailbox-scoped key.
SAMVA_MAILBOX_IDThe mailbox that receives messages.
SAMVA_WEBHOOK_SECRETThe 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.

Deploy with Vercel

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.

app/api/samva/route.ts
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

Related documentation

On this page