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
message	SMS/MMS text messages to mobile phones
line	LINE messaging platform

Channel Selection

              Which channel?
                    |
      +-------------+-------------+
      |                           |
      v                           v
+-----------+               +-----------+
|  message  |               |   line    |
| (SMS/MMS) |               | messaging |
+-----+-----+               +-----+-----+
      |                           |
      v                           v
Short,                      Real-time,
immediate                   interactive
(< 160 chars)               chat-based

Conversation Lifecycle

A conversation is created automatically when VoIPBIN receives an inbound message (SMS/MMS or LINE) or when a message is sent via the API. Conversations persist as long as they are not deleted.

Conversation Message States

Messages within a conversation move through predictable states.

Message sent/received
       |
       v
+--------------+
| progressing  |
+------+-------+
       |
  +----+----+
  |         |
  v         v
+------+ +--------+
| done | | failed |
+------+ +--------+

Message Status Descriptions

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

How Conversations Are Created

Conversations are created automatically by VoIPBIN when inbound messages arrive or when messages are sent through flows. You can list existing conversations with GET https://api.voipbin.net/v1.0/conversations.

Note

AI Implementation Hint

There is no POST /conversations endpoint. Conversations are created automatically based on incoming messages (SMS/MMS or LINE) or outbound message flow actions. To view conversations, use GET https://api.voipbin.net/v1.0/conversations. Each conversation links a self address (your number) to a peer address (the external party). The type field is message for SMS/MMS or line for LINE messaging.

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!"
    }'

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_deleted	Conversation deleted
conversation_message_created	New message created in conversation
conversation_message_updated	Message status or content updated
conversation_message_deleted	Message deleted from 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>",
    "customer_id": "<string>",
    "owner_type": "<string>",
    "owner_id": "<string>",
    "account_id": "<string>",
    "name": "<string>",
    "detail": "<string>",
    "type": "<string>",
    "dialog_id": "<string>",
    "self": {
        ...
    },
    "peer": {
        ...
    },
    "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.
customer_id (UUID): The customer’s ID. Obtained from the id field of GET /customers.
owner_type (enum string): The type of the owner of this conversation (e.g., agent).
owner_id (UUID): The owner’s unique identifier.
account_id (UUID): The messaging account ID associated with this conversation.
name (String): A human-readable name for the conversation (e.g., “Customer Support #1234”).
detail (String): Additional description or context for the conversation.
type (enum string): The channel type of this conversation. See Type.
dialog_id (String): An identifier associated with the channel dialog (e.g., a phone number or Line chatroom ID).
self (Object): The local party’s address in this conversation. See Address.
peer (Object): The remote party’s address 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",
    "customer_id": "5e4a0680-804e-11ec-8477-2fea5968d85b",
    "owner_type": "agent",
    "owner_id": "3a4b5c6d-7e8f-9012-3456-789abcdef012",
    "account_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "conversation",
    "detail": "conversation detail",
    "type": "message",
    "dialog_id": "+673802",
    "self": {
        "type": "tel",
        "target": "+14703298699",
        "target_name": "",
        "name": "",
        "detail": ""
    },
    "peer": {
        "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"
}

Type

Conversation’s type.

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

Message

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

id (UUID): The message’s unique identifier within the conversation.
customer_id (UUID): The customer’s ID. Obtained from the id field of GET /customers.
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 (UUID): An identifier associated with the channel reference.
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",
    "customer_id": "5e4a0680-804e-11ec-8477-2fea5968d85b",
    "conversation_id": "64558b45-40a8-43db-b814-9c0dbf6d47b5",
    "direction": "incoming",
    "status": "received",
    "reference_type": "line",
    "reference_id": "Ud871bcaf7c3ad13d2a0b0d78a42a287f",
    "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.

Conversation Account

Account

{
    "id": "<string>",
    "customer_id": "<string>",
    "type": "<string>",
    "name": "<string>",
    "detail": "<string>",
    "message_flow_id": "<string>",
    "tm_create": "<string>",
    "tm_update": "<string>",
    "tm_delete": "<string>"
}

id (UUID): The conversation account’s unique identifier. Returned when creating via POST /conversation-accounts or listing via GET /conversation-accounts.
customer_id (UUID): The customer who owns this conversation account. Obtained from the id field of GET /customers.
type (enum string): The messaging platform type. See Type.
name (string): A human-readable name for this conversation account.
detail (string): Additional description or notes about this account.
message_flow_id (UUID): The flow to execute when a message is received on this account. Obtained from the id field of GET /flows. Set to 00000000-0000-0000-0000-000000000000 if no flow is assigned.
tm_create (string, ISO 8601): Timestamp when this account was created.
tm_update (string, ISO 8601): Timestamp of the last update to this account.
tm_delete (string, ISO 8601): Timestamp when this account was deleted. Set to 9999-01-01 00:00:00.000000 if not deleted.

Type

All possible values for the type field:

Type	Description
line	LINE messaging platform account
sms	SMS messaging account

Example

{
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "customer_id": "5e4a0680-804e-11ec-8477-2fea5968d85b",
    "type": "line",
    "name": "Customer Support LINE",
    "detail": "LINE account for customer support inquiries",
    "message_flow_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "tm_create": "2024-03-01T10:00:00.000000Z",
    "tm_update": "2024-03-01T10:00:00.000000Z",
    "tm_delete": "9999-01-01T00:00:00.000000Z"
}

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 conversation already created by an incoming message (SMS/MMS via message type, or LINE via line type). Conversations are auto-created when messages arrive – there is no POST /conversations endpoint.
(Optional) A conversation account configured for the messaging channel (LINE credentials, etc.). Manage accounts via GET /conversation_accounts.

Note

AI Implementation Hint

Conversations are auto-created when an inbound message arrives on a configured channel (SMS/MMS or LINE). There is no POST /conversations endpoint to create conversations manually. The type field indicates the channel: message for SMS/MMS or line for LINE. Messages sent within a conversation incur per-channel delivery costs. When sending a message to a conversation, pass the conversation UUID in the URL path: POST /conversations/{id}/messages.

Get list of conversations

Example

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

{
    "result": [
        {
            "id": "a7bc12b7-f95c-43e6-82a1-38f4b7ff9b3f",
            "customer_id": "5e4a0680-804e-11ec-8477-2fea5968d85b",
            "owner_type": "agent",
            "owner_id": "eb1ac5c0-ff63-47e2-bcdb-5da9c336eb4b",
            "account_id": "c5d6e7f8-a9b0-1234-cdef-567890abcdef",
            "name": "conversation",
            "detail": "conversation detail",
            "type": "line",
            "dialog_id": "Ud871bcaf7c3ad13d2a0b0d78a42a287f",
            "self": {
                "type": "line",
                "target": "",
                "target_name": "me",
                "name": "",
                "detail": ""
            },
            "peer": {
                "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",
    "customer_id": "5e4a0680-804e-11ec-8477-2fea5968d85b",
    "owner_type": "agent",
    "owner_id": "eb1ac5c0-ff63-47e2-bcdb-5da9c336eb4b",
    "account_id": "c5d6e7f8-a9b0-1234-cdef-567890abcdef",
    "name": "conversation",
    "detail": "conversation detail",
    "type": "line",
    "dialog_id": "Ud871bcaf7c3ad13d2a0b0d78a42a287f",
    "self": {
        "type": "line",
        "target": "",
        "target_name": "me",
        "name": "",
        "detail": ""
    },
    "peer": {
        "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.",
        "medias": []
    }'

{
    "id": "0c8f23cb-e878-49bf-b69e-03f59252f217",
    "customer_id": "5e4a0680-804e-11ec-8477-2fea5968d85b",
    "conversation_id": "a7bc12b7-f95c-43e6-82a1-38f4b7ff9b3f",
    "direction": "outgoing",
    "status": "progressing",
    "reference_type": "line",
    "reference_id": "Ud871bcaf7c3ad13d2a0b0d78a42a287f",
    "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",
            "customer_id": "5e4a0680-804e-11ec-8477-2fea5968d85b",
            "conversation_id": "a7bc12b7-f95c-43e6-82a1-38f4b7ff9b3f",
            "direction": "outgoing",
            "status": "done",
            "reference_type": "line",
            "reference_id": "Ud871bcaf7c3ad13d2a0b0d78a42a287f",
            "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

How Conversations Are Created

Sending Messages

Receiving Messages

Cross-Channel Continuity

Event Types

Common Scenarios

Best Practices

Troubleshooting

Related Documentation

Conversation

Conversation

Example

Type

Message

Message

Example

Direction

Conversation Account

Account

Type

Example

Tutorial

Get list of conversations

Example

Get detail of conversation

Example

Send a message to the conversation

Example

Get list of conversation messages

Example