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

# Conversations

> Read and send messages in the Sendora unified inbox via API.

## Overview

The **Conversations API** gives you programmatic access to Sendora's unified inbox (Unibox): the place where all inbound replies across SMS, email, LinkedIn, and WhatsApp land in a single thread per lead.

With the API you can:

* List all conversations with filtering and pagination
* Read full message threads for any lead
* Send a message to a lead on any text channel
* Set the traffic-light signal (GREEN / YELLOW / RED) to classify intent

## Listing conversations

```bash theme={"dark"}
GET /api/v1/public/conversations
```

Query parameters:

| Param | Type | Description |
| - | - | - |
| `channel` | string | Filter by channel: `SMS`, `EMAIL`, `LINKEDIN`, `WHATSAPP` |
| `traffic_light` | string | Filter by signal: `GREEN`, `YELLOW`, `RED` |
| `archived` | boolean | `false` (default) shows active threads; `true` shows archived |
| `search` | string | Partial match against lead name or message preview |
| `cursor` | string | Pagination cursor from previous `next_cursor` |
| `limit` | integer | Page size 1 to 100 (default 50) |

```bash theme={"dark"}
# Only leads who replied positively (GREEN = interested)
GET /api/v1/public/conversations?traffic_light=GREEN&limit=20

# Unread replies on LinkedIn
GET /api/v1/public/conversations?channel=LINKEDIN
```

## Reading a thread

Get all messages for a specific lead in chronological order:

```bash theme={"dark"}
GET /api/v1/public/conversations/{lead_id}
```

Returns a `ConversationThread` with the lead's info and all messages:

```json theme={"dark"}
{
  "lead": {
    "id": "lead_abc",
    "first_name": "Sarah",
    "last_name": "Chen",
    "email": "sarah@techcorp.io",
    "traffic_light_status": "GREEN"
  },
  "messages": [
    {
      "id": "msg_001",
      "direction": "outbound",
      "channel": "EMAIL",
      "content": "Hi Sarah, I'd love to connect...",
      "created_at": "2026-06-20T09:00:00Z",
      "status": "delivered"
    },
    {
      "id": "msg_002",
      "direction": "inbound",
      "channel": "EMAIL",
      "content": "Hi! Yes, I'd be happy to chat.",
      "created_at": "2026-06-20T14:32:00Z"
    }
  ],
  "call_recording": null
}
```

If the most recent conversation was a voice call, `call_recording` contains the recording URL and transcript.

## Sending a message

Send a message to a lead on any text channel:

```bash theme={"dark"}
curl -X POST "https://api.sendora.ai/api/v1/public/conversations/{lead_id}/messages" \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "SMS",
    "content": "Hey Sarah, just wanted to follow up. Does Thursday at 2pm work?"
  }'
```

Sendora chooses the sending account for you: the account the lead's existing conversation runs on, and otherwise one picked by Sendora's sender rotation.

<Note>
  Voice (`VOICE`) is not supported via the conversations API, outbound calls are initiated through campaigns or the voice agent dashboard.
</Note>

Valid channels: `SMS`, `EMAIL`, `LINKEDIN`, `WHATSAPP`

## Setting the traffic light

Classify a lead's intent to help prioritize follow-up:

```bash theme={"dark"}
curl -X PATCH "https://api.sendora.ai/api/v1/public/conversations/{lead_id}/traffic-light" \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "traffic_light": "GREEN" }'
```

| Signal | Meaning |
| - | - |
| `GREEN` | Interested, prioritize follow-up |
| `YELLOW` | Neutral / needs more context |
| `RED` | Not interested / objection raised |

Sendora's AI classifier sets this automatically when a reply arrives, but you can override it here.

## Webhook integration

Subscribe to `reply.received` to trigger your workflow the moment a lead responds:

```json theme={"dark"}
{ "events": ["reply.received"] }
```

The webhook payload includes `channel`, `message_preview`, and `lead_id` so you can load the full thread on demand.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.