Conversation

Manage threaded conversations and message history across channels (SMS, voice, chat). Conversations group related messages into a single thread for tracking interaction history with a contact.

API Reference: Conversation endpoints

Overview

Note

AI Context

Complexity: Medium
Cost: Free (conversations are organizational containers; message delivery costs apply per channel)
Async: Yes. Messages sent within a conversation are delivered asynchronously. Use webhooks to receive delivery status and inbound message events.

VoIPBIN’s Conversation API provides a unified multi-channel messaging platform that enables seamless communication across SMS, MMS, email, chat, and social networking channels. Users can start a conversation through one channel and continue it through another without losing context.

With the Conversation API you can:

Create unified conversations across multiple channels
Switch channels seamlessly within the same conversation
Track message history across all channels
Manage participants dynamically
Receive real-time updates via webhooks

How Conversations Work

VoIPBIN Conversations acts as a unified hub that routes messages across different communication channels while maintaining conversation context.

Conversation Architecture

+----------+        +----------------+        +---------------+
|   SMS    |------->|                |------->|    SMS/MMS    |
+----------+        |                |        +---------------+
                    |                |
+----------+        |    VoIPBIN     |        +---------------+
|  Email   |------->|  Conversation  |------->|     Email     |
+----------+        |      Hub       |        +---------------+
                    |                |
+----------+        |                |        +---------------+
|   Chat   |------->|                |------->|   Chat/SNS    |
+----------+        +-------+--------+        +---------------+
                            |
                     +------+------+
                     |   Webhook   |
                     |  (events)   |
                     +-------------+

Key Components

Conversation: A container that groups related messages across channels
Participant: An endpoint (phone number, email, chat ID) in the conversation
Message: Content sent within a conversation via any channel
Channel: The communication method (SMS, MMS, email, chat, SNS)

Unified Conversation Flow

User                    VoIPBIN                     Recipient
  |                        |                            |
  | SMS: "Hello"           |                            |
  +----------------------->| Route to conversation      |
  |                        | (auto-detect or create)    |
  |                        +--------------------------->|
  |                        |              SMS delivered |
  |                        |                            |
  |                        |<---------------------------+
  |                        |   Email reply: "Hi there"  |
  |                        |                            |
  |<-----------------------+                            |
  | Webhook: message       |                            |
  | received in same       |                            |
  | conversation           |                            |

Channel Types

VoIPBIN supports multiple communication channels within a single conversation.

Supported Channels

Channel	Description
SMS	Standard text messages to mobile phones
MMS	Multimedia messages with images, videos, audio
Email	Email messages with attachments
Chat	Real-time web/mobile chat
SNS	Social networking services (WhatsApp, Facebook Messenger, etc.)

Channel Selection

                  Which channel?
                        |
      +-----------------+------------------+
      |                 |                  |
      v                 v                  v
+----------+      +----------+       +----------+
|   SMS    |      |  Email   |       |   Chat   |
+----+-----+      +----+-----+       +----+-----+
     |                 |                  |
     v                 v                  v
Short,            Formal,            Real-time,
immediate         detailed           interactive
(< 160 chars)     with attachments   presence-aware

Conversation Lifecycle

Conversations move through predictable states.

Conversation States

Message received/sent
       |
       v
+------------+
|   active   |<-----------------+
+-----+------+                  |
      |                         |
      | no activity             | new message
      | (timeout)               |
      v                         |
+------------+                  |
|   idle     |------------------+
+-----+------+
      |
      | explicit close
      | or long timeout
      v
+------------+
|   closed   |
+------------+

State Descriptions

State	What’s happening
active	Conversation has recent activity, participants engaged
idle	No recent messages, but conversation still open
closed	Conversation ended, new messages create new conversation

Conversation Rooms

VoIPBIN automatically organizes messages into distinct conversation rooms based on participants and channels.

Room Matching Logic

New message arrives
       |
       v
+--------------------+
| Check participants |
| and channel        |
+--------+-----------+
         |
         v
+--------------------+     Yes    +--------------------+
| Match existing     |----------->| Add message to     |
| conversation?      |            | existing room      |
+--------+-----------+            +--------------------+
         |
         | No
         v
+--------------------+
| Create new         |
| conversation room  |
+--------------------+

Room Benefits

Messages automatically grouped by context
No manual conversation management needed
Full history preserved across channel switches
Participants can be added or removed dynamically

Creating Conversations

Create conversations explicitly or let VoIPBIN auto-create them.

Note

AI Implementation Hint

Conversations are automatically matched based on participants and channel. Before creating a new conversation, check if an active conversation already exists between the same participants to avoid duplicates. Sending a message to a closed conversation will create a new one.

Create a Conversation

$ curl -X POST 'https://api.voipbin.net/v1.0/conversations?token=<token>' \
    --header 'Content-Type: application/json' \
    --data '{
        "name": "Customer Support #1234",
        "participants": [
            {
                "type": "tel",
                "target": "+15551234567"
            },
            {
                "type": "email",
                "target": "[email protected]"
            }
        ]
    }'

Add Participant

$ curl -X POST 'https://api.voipbin.net/v1.0/conversations/<conversation-id>/participants?token=<token>' \
    --header 'Content-Type: application/json' \
    --data '{
        "type": "tel",
        "target": "+15559876543"
    }'

Sending Messages

Send messages to a conversation and VoIPBIN routes to appropriate channels.

Send Message Flow

Your App                    VoIPBIN                 Participants
    |                          |                         |
    | POST /conversations/     |                         |
    |   {id}/messages          |                         |
    +------------------------->|                         |
    |                          | Determine best channel  |
    |                          | for each participant    |
    |                          |                         |
    |                          +-- SMS ----------------->|
    |                          +-- Email --------------->|
    |                          +-- Chat ---------------->|
    |  message_id              |                         |
    |<-------------------------+                         |
    |                          |                         |

Send Message Example

$ curl -X POST 'https://api.voipbin.net/v1.0/conversations/<conversation-id>/messages?token=<token>' \
    --header 'Content-Type: application/json' \
    --data '{
        "text": "Your order has been shipped!",
        "medias": [
            {
                "type": "image/png",
                "url": "https://example.com/tracking-map.png"
            }
        ]
    }'

Channel Selection Priority

When sending to a conversation, VoIPBIN selects the best channel based on:

Participant’s last active channel
Message content (media requires MMS/email)
Participant preferences
Channel availability

Receiving Messages

VoIPBIN delivers inbound messages to your application via webhooks.

Webhook Delivery

Participant             VoIPBIN                      Your App
     |                     |                            |
     | SMS reply           |                            |
     +-------------------->|                            |
     |                     | Match to conversation      |
     |                     |                            |
     |                     | POST /your-webhook         |
     |                     | {conversation_message}     |
     |                     +--------------------------->|
     |                     |                            |
     |                     |            200 OK          |
     |                     |<---------------------------+
     |                     |                            |

Inbound Message Webhook

{
    "type": "conversation_message_received",
    "data": {
        "conversation_id": "conv-abc-123",
        "message": {
            "id": "msg-xyz-789",
            "participant": {
                "type": "tel",
                "target": "+15559876543"
            },
            "channel": "sms",
            "text": "Thanks for the update!",
            "direction": "inbound",
            "tm_create": "2024-01-15T10:30:00Z"
        }
    }
}

Cross-Channel Continuity

The key feature of VoIPBIN Conversations is seamless channel switching.

Cross-Channel Example

+---------------------------------------------------------------+
| Conversation: "Order Support #5678"                           |
+---------------------------------------------------------------+
|                                                               |
| [10:00] Customer via SMS:                                     |
|         "When will my order arrive?"                          |
|                                                               |
| [10:05] Support via Email:                                    |
|         "Your order is scheduled for Friday delivery.         |
|          Here's the tracking link: ..."                       |
|         [attachment: tracking-details.pdf]                    |
|                                                               |
| [10:10] Customer via Chat:                                    |
|         "Can I change the delivery address?"                  |
|                                                               |
| [10:12] Support via Chat:                                     |
|         "Yes, I've updated it. Sending confirmation..."       |
|                                                               |
| [10:13] Support via SMS:                                      |
|         "Address updated! Confirmation sent to your email."   |
|                                                               |
+---------------------------------------------------------------+

Benefits

Single conversation ID tracks all interactions
Full history visible regardless of channel
Participants can use their preferred channel
Agents see unified view of all messages

Event Types

VoIPBIN sends webhook events for conversation activities.

Event	When it fires
conversation_created	New conversation started
conversation_updated	Conversation metadata changed
conversation_closed	Conversation ended
conversation_message_received	Inbound message from participant
conversation_message_sent	Outbound message delivered
conversation_participant_added	New participant joined
conversation_participant_removed	Participant left conversation

Common Scenarios

Scenario 1: Customer Support Ticket

Unified support across channels.

Customer: SMS "Having login issues"
     |
     v
+---------------------------+
| VoIPBIN creates           |
| conversation              |
+---------------------------+
     |
     v
Support agent responds via email
(includes detailed instructions + screenshots)
     |
     v
Customer follows up via chat
(real-time troubleshooting)
     |
     v
Issue resolved - conversation closed
(full history in one place)

Scenario 2: Order Notifications

Multi-channel order updates.

+--------------------------------------------+
| Order placed                               |
| -> SMS: "Order confirmed! #12345"          |
+--------------------------------------------+
                   |
                   v
+--------------------------------------------+
| Order shipped                              |
| -> Email: Tracking details + invoice       |
| -> SMS: "Your order shipped!"              |
+--------------------------------------------+
                   |
                   v
+--------------------------------------------+
| Out for delivery                           |
| -> SMS: "Arriving today by 5pm"            |
+--------------------------------------------+
                   |
                   v
+--------------------------------------------+
| Delivered                                  |
| -> SMS: "Delivered! Rate your experience"  |
+--------------------------------------------+

Scenario 3: Appointment Reminders

Escalating reminders across channels.

3 days before:
    Email -> Detailed appointment info

1 day before:
    SMS -> "Reminder: Appointment tomorrow at 2pm"

2 hours before:
    SMS -> "Your appointment is in 2 hours"

Customer replies via any channel
    -> All responses in same conversation

Best Practices

1. Channel Selection

Use SMS for urgent, short notifications
Use email for detailed information with attachments
Use chat for real-time, interactive conversations
Respect participant channel preferences

2. Conversation Organization

Use descriptive conversation names
Set appropriate conversation timeouts
Archive completed conversations
Tag conversations for easy filtering

3. Message Content

Keep messages channel-appropriate
Include context when switching channels
Use consistent tone across channels
Avoid duplicate notifications

4. Participant Management

Verify participant endpoints before adding
Remove inactive participants
Handle bounce-backs and failures gracefully

Troubleshooting

Message Issues

Symptom	Solution
Message not delivered	Check participant endpoint validity; verify channel is available for participant
Wrong channel selected	Check channel selection priority; verify participant preferences
Duplicate messages	Check for retry logic; ensure idempotency using message IDs

Conversation Issues

Symptom	Solution
Messages in wrong conversation	Check participant matching; verify conversation is active (not closed)
New conversation created unexpectedly	Previous conversation may have timed out; check conversation state
Participant can’t receive messages	Verify endpoint; check channel availability; review delivery errors

Webhook Issues

Symptom	Solution
Missing events	Verify webhook URL configuration; check endpoint returns 200 OK within 5 seconds
Delayed events	Check webhook endpoint performance; review retry queue

Conversation

{
    "id": "<string>",
    "name": "<string>",
    "detail": "<string>",
    "reference_type": "<string>",
    "reference_id": "<string>",
    "source": {
        ...
    },
    "participants": [
        ...
    ],
    "tm_create": "<string>",
    "tm_update": "<string>",
    "tm_delete": "<string>"
}

id (UUID): The conversation’s unique identifier. Returned when creating via POST /conversations or listing via GET /conversations.
name (String): A human-readable name for the conversation (e.g., “Customer Support #1234”).
detail (String): Additional description or context for the conversation.
reference_type (enum string): The channel type that initiated this conversation. See Reference type.
reference_id (String): An identifier associated with the reference channel (e.g., a phone number or Line user ID).
source (Object): The conversation’s source address. See Address.
participants (Array of Object): List of participant addresses in this conversation. See Address.
tm_create (string, ISO 8601): Timestamp when the conversation was created.
tm_update (string, ISO 8601): Timestamp of the last update.
tm_delete (string, ISO 8601): Timestamp of deletion (soft delete).

Note

AI Implementation Hint

Timestamps set to 9999-01-01 00:00:00.000000 indicate the event has not yet occurred. For example, tm_delete with this value means the conversation has not been deleted.

Example

{
    "id": "bdc9d9f5-706c-4e2d-9be7-7dc1e5fd45a0",
    "name": "conversation",
    "detail": "conversation detail",
    "reference_type": "message",
    "reference_id": "+673802",
    "source": {
        "type": "tel",
        "target": "+14703298699",
        "target_name": "",
        "name": "",
        "detail": ""
    },
    "participants": [
        {
            "type": "tel",
            "target": "+14703298699",
            "target_name": "",
            "name": "",
            "detail": ""
        },
        {
            "type": "tel",
            "target": "+673802",
            "target_name": "",
            "name": "",
            "detail": ""
        }
    ],
    "tm_create": "2022-06-23 05:05:40.950834",
    "tm_update": "2022-06-23 05:05:40.950842",
    "tm_delete": "9999-01-01 00:00:00.000000"
}

Reference type

Conversation’s reference type.

Reference type	Description
message	Conversation initiated via SMS/MMS messaging channel.
line	Conversation initiated via Line messaging platform.

Message

{
    "id": "<string>",
    "conversation_id": "<string>",
    "direction": "<string>",
    "status": "<string>",
    "reference_type": "<string>",
    "reference_id": "<string>",
    "source": {
        ...
    },
    "text": "<string>",
    "medias": [],
    "tm_create": "<string>",
    "tm_update": "<string>",
    "tm_delete": "<string>"
}

id (UUID): The message’s unique identifier within the conversation.
conversation_id (UUID): The parent conversation’s ID. Obtained from GET /conversations or from the URL path when sending messages.
direction (enum string): Whether the message is incoming or outgoing. See Direction.
status (enum string): The message’s delivery status (e.g., sent, received, failed).
reference_type (enum string): The channel used for this message. See Reference type.
reference_id (String): An identifier associated with the channel (e.g., a Line user ID or phone number).
source (Object): The sender’s address for this message. See Address.
text (String): The message body text content.
medias (Array of Object): List of media attachments (images, videos, etc.) included with the message.
tm_create (string, ISO 8601): Timestamp when the message was created.
tm_update (string, ISO 8601): Timestamp of the last status update.
tm_delete (string, ISO 8601): Timestamp of deletion (soft delete).

Note

AI Implementation Hint

Timestamps set to 9999-01-01 00:00:00.000000 indicate the event has not yet occurred. For example, tm_delete with this value means the message has not been deleted.

Example

{
    "id": "cc46341b-f00a-452f-b527-19c85d030eaf",
    "conversation_id": "64558b45-40a8-43db-b814-9c0dbf6d47b5",
    "direction": "incoming",
    "status": "received",
    "reference_type": "line",
    "reference_id": "Ud871bcaf7c3ad13d2a0b0d78a42a287f",
    "source": {
        "type": "line",
        "target": "Ud871bcaf7c3ad13d2a0b0d78a42a287f",
        "target_name": "",
        "name": "",
        "detail": ""
    },
    "text": "안녕",
    "medias": [],
    "tm_create": "2022-06-24 04:28:51.558082",
    "tm_update": "2022-06-24 04:28:51.558090",
    "tm_delete": "9999-01-01 00:00:00.000000"
}

Direction

Message’s direction.

Direction	Description
incoming	Incoming message from a participant towards VoIPBIN. Delivered to your application via webhook.
outgoing	Outgoing message sent from your application via VoIPBIN to a conversation participant.

Tutorial

Before working with conversations, you need:

An authentication token. Obtain one via POST /auth/login or use an access key from GET /accesskeys.
A reference_type value indicating the channel for the conversation (e.g., message for SMS/MMS, line for Line). See Reference type.
(Optional) Participant addresses in the appropriate format for the channel (E.164 phone numbers for SMS, Line user IDs for Line).

Note

AI Implementation Hint

Conversations are free to create, but messages sent within them incur per-channel delivery costs (SMS, email, etc.). When sending a message to a conversation via POST /conversations/{id}/messages, the conversation ID is passed in the URL path, not the request body.

Setup the conversation

$ curl --location --request POST 'https://api.voipbin.net/v1.0/conversations/setup?token=<YOUR_AUTH_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "reference_type": "line"
}'

Get list of conversations

Example

$ curl -k --location --request GET 'https://api.voipbin.net/v1.0/conversations?token=<YOUR_AUTH_TOKEN>'

{
    "result": [
        {
        "id": "a7bc12b7-f95c-43e6-82a1-38f4b7ff9b3f",
        "name": "conversation",
        "detail": "conversation detail",
        "reference_type": "line",
        "reference_id": "Ud871bcaf7c3ad13d2a0b0d78a42a287f",
        "participants": [
            {
            "type": "line",
            "target": "",
            "target_name": "me",
            "name": "",
            "detail": ""
            },
            {
            "type": "line",
            "target": "Ud871bcaf7c3ad13d2a0b0d78a42a287f",
            "target_name": "Unknown",
            "name": "",
            "detail": ""
            }
        ],
        "tm_create": "2022-06-17 06:06:14.446158",
        "tm_update": "2022-06-17 06:06:14.446167",
        "tm_delete": "9999-01-01 00:00:00.000000"
        }
    ],
    "next_page_token": "2022-06-17 06:06:14.446158"
}

Get detail of conversation

Example

$ curl --location --request GET 'https://api.voipbin.net/v1.0/conversations/a7bc12b7-f95c-43e6-82a1-38f4b7ff9b3f?token=<YOUR_AUTH_TOKEN>'

{
    "id": "a7bc12b7-f95c-43e6-82a1-38f4b7ff9b3f",
    "name": "conversation",
    "detail": "conversation detail",
    "reference_type": "line",
    "reference_id": "Ud871bcaf7c3ad13d2a0b0d78a42a287f",
    "participants": [
        {
            "type": "line",
            "target": "",
            "target_name": "me",
            "name": "",
            "detail": ""
        },
        {
            "type": "line",
            "target": "Ud871bcaf7c3ad13d2a0b0d78a42a287f",
            "target_name": "Unknown",
            "name": "",
            "detail": ""
        }
    ],
    "tm_create": "2022-06-17 06:06:14.446158",
    "tm_update": "2022-06-17 06:06:14.446167",
    "tm_delete": "9999-01-01 00:00:00.000000"
}

Send a message to the conversation

Example

$ curl --location --request POST 'https://api.voipbin.net/v1.0/conversations/a7bc12b7-f95c-43e6-82a1-38f4b7ff9b3f/messages?token=<YOUR_AUTH_TOKEN>' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "text": "Hello, this is a test message. Thank you for your time."
    }'

{
    "id": "0c8f23cb-e878-49bf-b69e-03f59252f217",
    "conversation_id": "a7bc12b7-f95c-43e6-82a1-38f4b7ff9b3f",
    "status": "sent",
    "reference_type": "line",
    "reference_id": "Ud871bcaf7c3ad13d2a0b0d78a42a287f",
    "source_target": "",
    "text": "Hello, this is a test message. Thank you for your time.",
    "medias": [],
    "tm_create": "2022-06-20 03:07:11.372307",
    "tm_update": "2022-06-20 03:07:11.372315",
    "tm_delete": "9999-01-01 00:00:00.000000"
}

Get list of conversation messages

Example

$ curl --location --request GET 'https://api.voipbin.net/v1.0/conversations/a7bc12b7-f95c-43e6-82a1-38f4b7ff9b3f/messages?token=<YOUR_AUTH_TOKEN>'

{
    "result": [
        {
            "id": "0c8f23cb-e878-49bf-b69e-03f59252f217",
            "conversation_id": "a7bc12b7-f95c-43e6-82a1-38f4b7ff9b3f",
            "status": "sent",
            "reference_type": "line",
            "reference_id": "Ud871bcaf7c3ad13d2a0b0d78a42a287f",
            "source_target": "",
            "text": "Hello, this is a test message. Thank you for your time.",
            "medias": [],
            "tm_create": "2022-06-20 03:07:11.372307",
            "tm_update": "2022-06-20 03:07:11.372315",
            "tm_delete": "9999-01-01 00:00:00.000000"
        },
        ...
    ],
    "next_page_token": "2022-06-17 06:06:14.948432"
}

Conversation

Overview

How Conversations Work

Channel Types

Conversation Lifecycle

Conversation Rooms

Creating Conversations

Sending Messages

Receiving Messages

Cross-Channel Continuity

Event Types

Common Scenarios

Best Practices

Troubleshooting

Related Documentation

Conversation

Conversation

Example

Reference type

Message

Message

Example

Direction

Tutorial

Setup the conversation

Get list of conversations

Example

Get detail of conversation

Example

Send a message to the conversation

Example

Get list of conversation messages

Example