# Inbound SMS

Canonical URL: https://texttree.ai/en/docs/inbound-sms/
Markdown URL: https://texttree.ai/en/docs/inbound-sms.md
Page type: docs
Translation status: approved
Legal status: not_required

## Summary

Route inbound SMS into webhooks, conversations, contacts, and AI handoff workflows.

## Source content

Inbound SMS creates a received message, updates the conversation, and can trigger configured webhook endpoints.

## Received message payload

```json
{
  "type": "message.received",
  "message_id": "msg_123",
  "conversation_id": "conv_123",
  "from": "+15551234567",
  "phone_number": "+15557654321",
  "body": "Can I reschedule?",
  "received_at": "2026-04-28T14:00:00Z"
}
```

Use inbound routing for AI agents, support inboxes, lead qualification, and appointment workflows.

## AI agent routing pattern

1. Configure an endpoint in the Webhooks page.
2. Subscribe to `message.received` and `conversation.updated`.
3. Have your service decide whether the AI agent should reply, pause, or hand off.
4. Send the reply through `POST /api/v1/messages` using the same conversation metadata.

```js
export async function handleInboundTextreeEvent(event) {
  if (event.type !== "message.received") {
    return;
  }

  const shouldEscalate = event.body.toLowerCase().includes("human");

  if (shouldEscalate) {
    await pauseAgentAndNotifyOperator(event.conversation_id);
    return;
  }

  await fetch("https://api.texttree.ai/api/v1/messages", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.TEXTREE_ACCESS_TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      phone_number: event.from,
      body: "Thanks. I can help with that.",
      metadata: {
        conversation_id: event.conversation_id,
        source: "ai_agent",
      },
    }),
  });
}
```

## Human handoff behavior

Inbound conversations can move between these operator states:

- `AI active`
- `Human takeover`
- `Paused`
- `Resolved`

When the AI is paused or a human has taken over, your integration should stop automated replies
until the conversation is resumed.