VoIPBin Documentation
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 |