> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wassist.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Build on Wassist

> The three ways to put your code into a WhatsApp conversation: webhooks, managed agents with tools, and Apps.

Every Wassist integration is one of three things, depending on **who writes the replies** and **where your code runs**:

<CardGroup cols={3}>
  <Card title="Webhooks" icon="webhook" href="#webhooks-your-code-owns-the-conversation">
    **Your code writes every reply.** Wassist forwards each message and you answer through the API.
  </Card>

  <Card title="Managed agents + tools" icon="robot" href="#managed-agents-and-tools-wassist-owns-the-conversation">
    **Wassist's agent writes the replies** and calls your APIs when it needs data or an action.
  </Card>

  <Card title="Apps (alpha)" icon="blocks" href="#apps-alpha-installable-tools-that-know-the-conversation">
    **Your MCP server, packaged** so agents can install it, with signed context and API access on every call.
  </Card>
</CardGroup>

```mermaid theme={null}
flowchart LR
    C[WhatsApp customer] <--> N[Your number]
    N -->|routing: webhook| WH[Your webhook]
    WH -->|messages.send| N
    N -->|routing: agent| A[Wassist agent]
    A -->|API tool| API[Your REST endpoint]
    A -->|Connector| MCP[Any MCP server]
    A -->|App tool + signed context| APP[Your App]
    APP -->|Wassist API as the installer| N
```

## Which one do I want?

* **You already have an agent or bot** (LangChain, OpenAI Agents SDK, [Vercel eve](https://github.com/vercel/eve), a rules engine) → **Webhooks**.
* **You want an agent live today** and only need to plug in your data, like order status or bookings → **Managed agent + API tools**.
* **You're building tools that need to know who they're talking to** (loyalty points, reviews, bookings, a helpdesk), which customer, and which conversation → **App**.

You can mix them. A common setup is a managed agent that answers most questions, an App or API tool for your back office, and a webhook that takes over individual conversations when a human or your own system needs them.

<Tip>
  Building a product where **your own customers** connect their WhatsApp numbers? Both webhooks and managed agents work across many accounts from one organization. See [Run WhatsApp for your users](/guides/platforms/manage-whatsapp-for-your-users).
</Tip>

***

## Webhooks: your code owns the conversation

Set a number's routing to **Webhook** and Wassist stops running the agent. Each inbound message arrives at your URL as a signed `subscription.message.received` event, and you reply with the Messages API.

```ts theme={null}
const event = Wassist.webhooks.constructEvent(rawBody, signatureHeader, WEBHOOK_SECRET);

if (event.event === "subscription.message.received") {
  await wassist.conversations.messages.send(event.conversationId, {
    type: "text",
    text: { body: await myAgent.reply(event.message.body) },
  });
}
```

| You get                                                        | You do                                                                   |
| -------------------------------------------------------------- | ------------------------------------------------------------------------ |
| Signed, retried, replayable deliveries with an idempotency key | Verify the signature and reply within 10 seconds, or ack and reply later |
| The message text, media URLs, button taps and ad referral      | Keep your own state keyed by `conversationId`                            |
| Typing indicators, read receipts and templates through the API | Send a template once the 24-hour window has closed                       |

Routing can be set per number or per conversation. For example, a managed agent can run the number while you `conversations.subscribe()` a single customer to your webhook.

<CardGroup cols={3}>
  <Card title="Hello world" icon="play" href="/quickstart/webhook-routing">
    A working handler on the sandbox in 5 minutes.
  </Card>

  <Card title="Conversation routing" icon="route" href="/guides/webhooks/routing">
    Per-number and per-conversation modes, plus lifecycle events.
  </Card>

  <Card title="Webhook reference" icon="webhook" href="/concepts/webhooks">
    Signing, retries, event catalogue and replay.
  </Card>
</CardGroup>

***

## Managed agents and tools: Wassist owns the conversation

Set routing to **Agent** and Wassist runs the whole loop: an LLM with your prompt, model and thinking-effort settings, conversation memory and WhatsApp formatting. You extend what it can do from the agent's **Capabilities** page:

| Capability                     | What it is                                                                        | Your side                                                                                           |
| ------------------------------ | --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| **API tools**                  | One HTTPS endpoint the agent calls with parameters it extracts from the chat      | Any REST endpoint. Each call carries `X-Wassist-Conversation-Id` and `X-Wassist-Contact-Id` headers |
| **Website tools**              | Live lookups on a web page                                                        | Nothing                                                                                             |
| **Connector tools**            | Tools from any MCP server, chosen per agent                                       | An MCP server (no auth or OAuth)                                                                    |
| **Shopify stores**             | Catalogue, policies, customer login and orders                                    | [Install the Shopify app](/guides/shopify/install-app)                                              |
| **Apps**                       | Tools from an installed Wassist App                                               | See [Apps](#apps-alpha-installable-tools-that-know-the-conversation)                                |
| **Agent and support handoffs** | Pass the chat to another agent, or to Gorgias, eDesk or the WhatsApp Business app | Nothing                                                                                             |

An API tool is just a JSON description of a request:

```json theme={null}
{
  "url": "https://api.acme.com/orders/{order_id}",
  "method": "GET",
  "path_params": {
    "order_id": {
      "type": "string",
      "input": { "type": "description", "description": "The order number, like ACM-12345" }
    }
  },
  "request_headers": {
    "Authorization": { "type": "string", "input": { "type": "value", "value": "Bearer sk_live_..." } }
  }
}
```

`description` inputs are filled in by the model from the conversation, and `value` inputs are fixed. Values can include `%PHONE_NUMBER%` and `%CALLBACK_URL%` (POST to it later to send a follow-up message).

<CardGroup cols={3}>
  <Card title="Hello world" icon="play" href="/quickstart/managed-agent">
    An agent replying on the sandbox in 2 minutes.
  </Card>

  <Card title="Configure tools" icon="plug" href="/guides/configure-tools">
    API tools, connectors, handoffs and more.
  </Card>

  <Card title="Deploy" icon="rocket" href="/guides/deploy-agent">
    Put the agent on your own number.
  </Card>
</CardGroup>

***

## Apps (alpha): installable tools that know the conversation

<Warning>
  Apps are in alpha, so the manifest and API may change. Email [contact@wassist.app](mailto:contact@wassist.app) to join the alpha group.
</Warning>

An App is an MCP server plus a manifest (name, icon, MCP URL, who logs in). You install it on your organization and pick which agents get which tools. In the alpha, an App can only be installed on the organization that owns it. Compared with a plain connector, an App adds three things:

1. **Signed context on every tool call.** `_meta` carries the installation, organization, agent and session, plus a JWT signed with your client secret.
2. **API access as the installer.** Your client ID and secret, plus the installation ID, give you the whole [v1 API](/api-reference/introduction) for that organization: read the conversation, send messages, look up the contact.
3. **Real auth modes.** `installer` (the business logs in once), `end_customer` (each WhatsApp customer logs in through a button the agent sends) or `none`.

```ts theme={null}
import { WassistApp } from "@wassist/sdk/apps";

const wassist = new WassistApp({ clientId: WASSIST_CLIENT_ID, clientSecret: WASSIST_CLIENT_SECRET });

server.registerTool("get_points", { description: "The customer's points balance", inputSchema: {} }, async (_args, extra) => {
  const ctx = wassist.verifyContextToken(extra._meta);  // which business, agent and session
  const channel = await wassist.resolveChannel(ctx);   // WhatsApp chat or dashboard test

  if (channel.type === "whatsapp") {
    const { contact } = await channel.getConversation();
    return { content: [{ type: "text", text: `${contact.name} has ${await points(contact.phoneNumber)} points` }] };
  }
  return { content: [{ type: "text", text: "Test customer has 120 points" }] };
});
```

### API tool, connector or App?

|                                          | API tool                            | Connector                             | App                                                  |
| ---------------------------------------- | ----------------------------------- | ------------------------------------- | ---------------------------------------------------- |
| What you provide                         | One REST endpoint                   | An MCP server                         | An MCP server and a manifest                         |
| Set up                                   | Per agent, as JSON                  | Once per organization, then per agent | Publish once, install, then pick agents and tools    |
| Auth                                     | Fixed headers                       | None or OAuth                         | None, installer OAuth or end-customer OAuth          |
| Knows the conversation                   | Conversation and contact ID headers | No                                    | Signed context, and the conversation through the API |
| Can call the Wassist API                 | With your own API key               | No                                    | Yes, as the installing organization                  |
| Versioned, with a draft and publish step | No                                  | No                                    | Yes                                                  |

<CardGroup cols={2}>
  <Card title="Build an App" icon="blocks" href="/guides/build-an-app">
    Wrap an existing MCP server in 15 minutes, or build a Wassist-aware one.
  </Card>

  <Card title="Example apps" icon="github" href="/guides/examples">
    Runnable MCP servers and webhook receivers to copy.
  </Card>
</CardGroup>