Inbound SMS

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

Received message payload

{
  "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.

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.