Conversations

Thread and manage communication history.

Overview

Conversations group messages by:

• Contact
• Channel
• Thread ID
• Session

Conversation Structure

Conversation
├── Contact (who)
├── Gateway (channel)
├── Messages (history)
└── Metadata (context)

Creating Conversations

Automatic

Conversations are created automatically when:

• New contact sends message
• Agent initiates contact
• Webhook receives message

Via API

curl -X POST .../conversations \
  -d '{
    "contact_id": "contact-123",
    "gateway_id": "telegram-bot",
    "metadata": {"topic": "support"}
  }'

Message Threading

Messages are grouped by conversation:

{
  "conversation_id": "conv-123",
  "messages": [
    {"role": "user", "content": "Help"},
    {"role": "assistant", "content": "How can I help?"},
    {"role": "user", "content": "Order issue"}
  ]
}

Identity Resolution

When a message arrives, the system:

1. Extracts sender identity (email, phone, etc.)
2. Looks up contact
3. Finds or creates conversation
4. Links message

Metadata

Store context with conversations:

{
  "metadata": {
    "topic": "billing",
    "priority": "high",
    "order_id": "ORD-123"
  }
}

Listing Conversations

All Conversations

curl .../conversations

By Contact

curl ".../conversations?contact_id=contact-123"

By Gateway

curl ".../conversations?gateway_id=telegram-bot"

API Reference

See Conversations API for complete endpoint documentation.