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

# Conversations

> Feather supports voice calls, SMS threads, email threads, and web chat using a shared conversation model.

Feather is multi-channel by design. The same agent foundation can be exposed through live voice, SMS, email, or web chat depending on the use case.

## Shared Conversation Concepts

Every conversation surface can carry:

* An agent or agent version
* Contact context such as `leadId`
* Variables used inside prompts or tools
* Metadata for CRM or reporting use
* Conversation records you can review later

## Conversation Surfaces

<CardGroup cols={2}>
  <Card title="Voice" icon="phone">
    Best for real-time qualification, support, intake, reminders, and transfers.
  </Card>

  <Card title="SMS" icon="messages">
    Best for short updates, follow-ups, opt-ins, confirmations, and workflow steps.
  </Card>

  <Card title="Email" icon="envelope">
    Best for longer follow-up, summaries, scheduling, and asynchronous outreach.
  </Card>

  <Card title="Web Chat" icon="message-dots">
    Best for embedded product or marketing site conversations.
  </Card>
</CardGroup>

## Voice Calls

Voice conversations can begin in two common ways:

* A user calls a number assigned to an inbound agent or squad
* You launch an outbound call with direct dispatch or a workflow step

### Direct Dispatch Example

```bash theme={"system"}
curl -X POST "https://prod.featherhq.com/api/v1/agent/AGENT_ID/dispatch" \
  -H "X-API-Key: $FEATHER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "versionId": "VERSION_ID",
    "outboundPhoneNumberId": "PHONE_NUMBER_ID",
    "leadId": "contact-123",
    "firstName": "Avery",
    "toPhoneNumber": "+14155550123",
    "variables": {
      "accountName": "Northwind Health"
    },
    "metadata": {
      "campaign": "renewal-q2"
    }
  }'
```

## SMS Threads

SMS uses persistent threads rather than one-off messages. This is the right model for follow-up, reminders, re-engagement, and workflow-based text outreach.

```bash theme={"system"}
curl -X POST "https://prod.featherhq.com/api/v1/threads" \
  -H "X-API-Key: $FEATHER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentVersionId": "TEXT_AGENT_VERSION_ID",
    "toPhoneNumber": "+14155550123",
    "fromPhoneNumber": "+14155550999",
    "fromPhoneNumberId": "FROM_PHONE_NUMBER_ID",
    "initialMessage": "Hi Taylor, this is Feather. I wanted to confirm whether tomorrow still works for your renewal review.",
    "leadId": "contact-123",
    "variables": {
      "accountName": "Northwind Health"
    }
  }'
```

## Email Threads

Email threads are outbound-initiated conversations tied to a deployed version. The version should have a verified sending domain configured before you start sending.

```bash theme={"system"}
curl -X POST "https://prod.featherhq.com/api/v1/email/threads" \
  -H "X-API-Key: $FEATHER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentVersionId": "TEXT_AGENT_VERSION_ID",
    "toEmail": "taylor@example.com",
    "subject": "Next steps for your renewal review",
    "firstMessage": "Thanks for taking the call today. Here is a short summary and the next action we discussed.",
    "leadId": "contact-123"
  }'
```

## Web Chat

Web chat threads are created on demand and return a short-lived token for the client. Chat creation is protected by an allowlist of approved domains.

```bash theme={"system"}
curl -X POST "https://prod.featherhq.com/api/v1/chat/threads" \
  -H "Content-Type: application/json" \
  -H "Origin: https://www.example.com" \
  -d '{
    "agentId": "WEB_CHAT_AGENT_ID"
  }'
```

Use [Update organization settings](/api-reference/organization/update-organization-settings) to manage `allowedChatDomains`.

## Design Guidance

* Use voice when the conversation needs urgency, nuance, or live transfer.
* Use SMS when a short asynchronous reply is enough.
* Use email when responses are longer or need richer written context.
* Use web chat for product surfaces or public website entry points.
* Reuse variables and metadata consistently across channels so workflows and reporting stay clean.

## Related API Reference

<CardGroup cols={2}>
  <Card title="Calls API" icon="code" href="/api-reference/calls/list-all-calls">
    Review completed call records.
  </Card>

  <Card title="SMS Threads API" icon="code" href="/api-reference/sms-threads/create-a-new-sms-thread">
    Start and manage text threads.
  </Card>

  <Card title="Email API" icon="code" href="/api-reference/email/create-an-email-thread">
    Create and inspect email threads.
  </Card>

  <Card title="Chat API" icon="code" href="/api-reference/chat/create-a-new-web-chat-thread">
    Launch web chat sessions.
  </Card>
</CardGroup>