Talk

Overview

VoIPBIN’s Talk API provides a modern messaging platform for real-time communication between agents. With support for threading, reactions, and group conversations, Talk enables efficient team collaboration and internal communication.

With the Talk API you can:

Create one-on-one and group conversations
Send messages with threading support
Add emoji reactions to messages
Attach media files to messages
Manage participants dynamically

How Talk Works

Talk provides a real-time messaging system where agents communicate through conversations called “talks.”

Talk Architecture

+----------+        +----------------+        +-----------+
| Agent A  |--API-->|    VoIPBIN     |--push->| Agent B   |
+----------+        |   Talk Hub     |        +-----------+
                    +----------------+
                           |
                    +------+------+
                    |  WebSocket  |
                    |  (real-time)|
                    +-------------+
                           |
          +----------------+----------------+
          v                v                v
     +---------+      +---------+      +---------+
     | Agent C |      | Agent D |      | Agent E |
     +---------+      +---------+      +---------+

Key Components

Talk: A conversation container with participants and messages
Participant: An agent who can send and receive messages in a talk
Message: Text, media, or system notifications within a talk
Thread: Messages grouped as replies to a parent message

Talk Types

VoIPBIN supports different talk types for various communication needs.

One-on-One Talk

Private conversation between two agents.

+-------------------------+
|      Talk (1:1)         |
+-------------------------+
|                         |
|  +---------+            |
|  | Agent A |<--------+  |
|  +---------+         |  |
|       |              |  |
|       v              |  |
|  +---------+         |  |
|  | Agent B |---------+  |
|  +---------+            |
|                         |
+-------------------------+

Group Talk

Multi-participant conversation for team discussions.

+---------------------------------------+
|            Talk (Group)               |
+---------------------------------------+
|                                       |
|  +---------+  +---------+  +-------+  |
|  | Agent A |  | Agent B |  | Agent |  |
|  +---------+  +---------+  |   C   |  |
|       |           |        +-------+  |
|       |           |            |      |
|       +-----+-----+------------+      |
|             |                         |
|             v                         |
|      +-------------+                  |
|      | All receive |                  |
|      |  messages   |                  |
|      +-------------+                  |
|                                       |
+---------------------------------------+

Talk Lifecycle

Talks and participants move through predictable states.

Talk States

POST /talks
      |
      v
+------------+
|   active   |<-----------------+
+-----+------+                  |
      |                         |
      | close or               | reopen
      | all leave              |
      v                         |
+------------+                  |
|   closed   |------------------+
+------------+

Participant States

POST /talks/{id}/participants
          |
          v
   +------------+
   |   active   |
   +-----+------+
         |
         | leave or removed
         v
   +------------+
   |    left    |
   +------------+

Creating and Managing Talks

Create talks and manage participants through the API.

Create a Talk

$ curl -X POST 'https://api.voipbin.net/v1.0/talks?token=<token>' \
    --header 'Content-Type: application/json' \
    --data '{
        "name": "Project Discussion",
        "participant_ids": [
            "agent-id-1",
            "agent-id-2",
            "agent-id-3"
        ]
    }'

Add Participant

$ curl -X POST 'https://api.voipbin.net/v1.0/talks/<talk-id>/participants?token=<token>' \
    --header 'Content-Type: application/json' \
    --data '{
        "agent_id": "agent-id-4"
    }'

Remove Participant

$ curl -X DELETE 'https://api.voipbin.net/v1.0/talks/<talk-id>/participants/<participant-id>?token=<token>'

Sending Messages

Send messages within talks with support for threading and media.

Send a Message

Agent                       VoIPBIN                    Other Participants
   |                           |                              |
   | POST /talks/{id}/messages |                              |
   +-------------------------->|                              |
   |                           | Broadcast to participants    |
   |                           +----------------------------->|
   |  message_id               |                              |
   |<--------------------------+                              |
   |                           |                              |

Basic Message Example:

$ curl -X POST 'https://api.voipbin.net/v1.0/talks/<talk-id>/messages?token=<token>' \
    --header 'Content-Type: application/json' \
    --data '{
        "text": "Hello team, let'\''s discuss the project status."
    }'

Reply to Message (Threading):

$ curl -X POST 'https://api.voipbin.net/v1.0/talks/<talk-id>/messages?token=<token>' \
    --header 'Content-Type: application/json' \
    --data '{
        "text": "I agree, we should prioritize the API work.",
        "parent_id": "parent-message-id"
    }'

Message with Media:

$ curl -X POST 'https://api.voipbin.net/v1.0/talks/<talk-id>/messages?token=<token>' \
    --header 'Content-Type: application/json' \
    --data '{
        "text": "Here is the design document.",
        "medias": [
            {
                "type": "application/pdf",
                "url": "https://storage.example.com/design-doc.pdf",
                "name": "design-document.pdf"
            }
        ]
    }'

Message Threading

Threading organizes conversations by grouping related messages.

Thread Structure

+---------------------------------------------------------------+
|  Talk: "Project Discussion"                                   |
+---------------------------------------------------------------+
|                                                               |
|  [Message 1] "What's the status of the API integration?"      |
|       |                                                       |
|       +-- [Reply 1.1] "Working on authentication now"         |
|       |                                                       |
|       +-- [Reply 1.2] "Should be done by Friday"              |
|       |                                                       |
|       +-- [Reply 1.3] "Great, let me know if you need help"   |
|                                                               |
|  [Message 2] "Meeting tomorrow at 2pm"                        |
|       |                                                       |
|       +-- [Reply 2.1] "I'll be there"                         |
|                                                               |
+---------------------------------------------------------------+

Thread Benefits

Keeps related discussions organized
Easy to follow conversation context
Reduces noise in main talk view

Message Reactions

Add emoji reactions to messages for quick feedback.

Add Reaction

$ curl -X POST 'https://api.voipbin.net/v1.0/messages/<message-id>/reactions?token=<token>' \
    --header 'Content-Type: application/json' \
    --data '{
        "emoji": "thumbsup"
    }'

Reaction Display

+-----------------------------------------------+
| [Agent A] "The deployment was successful!"    |
|                                               |
|  👍 3   🎉 2   ❤️ 1                           |
+-----------------------------------------------+

Common Reactions

Emoji	Common Use
👍	Agreement, acknowledgment
👎	Disagreement
❤️	Appreciation, love
🎉	Celebration, success
👀	Looking into it
✅	Done, completed

Message Types

Messages can be different types based on their origin.

Normal Messages

Regular messages sent by agents.

{
    "type": "normal",
    "agent_id": "agent-123",
    "text": "Let's schedule a call tomorrow."
}

System Messages

Automated notifications about talk events.

{
    "type": "system",
    "text": "Agent B joined the conversation."
}

{
    "type": "system",
    "text": "Agent C left the conversation."
}

Real-Time Updates

Receive real-time message updates via WebSocket.

WebSocket Connection

Agent                          VoIPBIN
   |                              |
   | WebSocket connect            |
   +----------------------------->|
   |                              |
   | Subscribe to talk events     |
   +----------------------------->|
   |                              |
   |<==== message_created ========|
   |<==== message_updated ========|
   |<==== participant_joined =====|
   |<==== reaction_added =========|
   |                              |

Event Types

Event	When it fires
message_created	New message sent to talk
message_updated	Message edited
message_deleted	Message removed
reaction_added	Reaction added to message
reaction_removed	Reaction removed from message
participant_joined	Agent joined the talk
participant_left	Agent left the talk

Common Scenarios

Scenario 1: Team Project Discussion

Create a group talk for project collaboration.

1. Create talk with team members
   POST /talks
   { "name": "Q1 Project", "participant_ids": [...] }

2. Send updates as messages
   POST /talks/{id}/messages
   { "text": "Sprint 1 completed!" }

3. Team reacts and replies in threads
   - Reactions: 🎉 👍
   - Thread: "Great work! What's next?"

Scenario 2: Quick Decision

Use reactions for quick polls.

[Agent A] "Should we deploy today? 👍 for yes, 👎 for no"
     |
     +-- 👍 Agent B
     +-- 👍 Agent C
     +-- 👍 Agent D
     +-- 👎 Agent E
     |
Result: 3-1, deploy approved

Scenario 3: Support Escalation

Internal discussion about customer issue.

+------------------------------------------------+
| Talk: "Customer Issue #12345"                  |
+------------------------------------------------+
|                                                |
| [Agent A] "Customer reporting payment failure" |
|                                                |
| [Agent B] "Let me check the logs"              |
|     |                                          |
|     +-- [Reply] "Found it - gateway timeout"   |
|     +-- [Reply] "Retrying the transaction"     |
|                                                |
| [Agent A] "Customer confirmed it works now"    |
|     👍 Agent B                                 |
|                                                |
+------------------------------------------------+

Best Practices

1. Talk Organization

Use descriptive talk names
Create separate talks for different topics
Archive inactive talks

2. Threading

Reply in threads to keep discussions organized
Use threads for detailed discussions
Keep main talk for announcements and new topics

3. Reactions

Use reactions for quick acknowledgments
Avoid over-reacting to every message
Use consistent reaction meanings in your team

4. Media Sharing

Use descriptive filenames
Keep file sizes reasonable
Reference shared files in message text

Troubleshooting

Message Issues

Symptom	Solution
Message not delivered	Check agent is participant in talk; verify WebSocket connection
Thread not showing	Verify parent_id is correct; check message exists
Media not loading	Check URL accessibility; verify file format

Participant Issues

Symptom	Solution
Can’t add participant	Verify agent exists; check talk is active
Not receiving messages	Check participant status; verify WebSocket subscription

Talk

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

id: Talk’s unique identifier.
customer_id: Customer’s unique identifier.
type: Talk’s type. See detail here.
tm_create: Timestamp when the talk was created.
tm_update: Timestamp when the talk was last updated.
tm_delete: Timestamp when the talk was deleted (soft delete).

Example

{
    "id": "e8b2e976-f043-44c8-bb89-e214e225e813",
    "customer_id": "5e4a0680-804e-11ec-8477-2fea5968d85b",
    "type": "normal",
    "tm_create": "2024-01-17 10:30:00.000000",
    "tm_update": "2024-01-17 10:30:00.000000",
    "tm_delete": ""
}

Type

Talk’s type determines whether it’s a one-on-one or group conversation.

Type	Description
normal	1:1 talk between two agents.
group	Group talk with multiple participants.

Message

{
    "id": "<string>",
    "customer_id": "<string>",
    "owner_type": "<string>",
    "owner_id": "<string>",
    "chat_id": "<string>",
    "parent_id": "<string>",
    "type": "<string>",
    "text": "<string>",
    "medias": [
        {
            "type": "<string>"
        }
    ],
    "metadata": {
        "reactions": [
            {
                "emoji": "<string>",
                "owner_type": "<string>",
                "owner_id": "<string>",
                "tm_create": "<string>"
            }
        ]
    },
    "tm_create": "<string>",
    "tm_update": "<string>",
    "tm_delete": "<string>"
}

id: Message’s unique identifier.
customer_id: Customer’s unique identifier.
owner_type: Type of the message owner (e.g., “agent”).
owner_id: Owner’s unique identifier.
chat_id: Talk’s unique identifier that this message belongs to.
parent_id: Parent message ID for threaded replies (optional).
type: Message type. See detail here.
text: Message text content.
medias: Array of media attachments.
metadata: Message metadata including reactions.
tm_create: Timestamp when the message was created.
tm_update: Timestamp when the message was last updated.
tm_delete: Timestamp when the message was deleted (soft delete).

Example

{
    "id": "a3c5e8f2-4d3a-4b5c-9e7f-1a2b3c4d5e6f",
    "customer_id": "5e4a0680-804e-11ec-8477-2fea5968d85b",
    "owner_type": "agent",
    "owner_id": "eb1ac5c0-ff63-47e2-bcdb-5da9c336eb4b",
    "chat_id": "e8b2e976-f043-44c8-bb89-e214e225e813",
    "parent_id": "b2d4f7a1-3c2e-4f5a-8d9c-2e3f4a5b6c7d",
    "type": "normal",
    "text": "That's a great idea! Let's proceed with that approach.",
    "medias": [],
    "metadata": {
        "reactions": [
            {
                "emoji": "👍",
                "owner_type": "agent",
                "owner_id": "47fe0b7c-7333-46cf-8b23-61e14e62490a",
                "tm_create": "2024-01-17 10:35:00.000000"
            }
        ]
    },
    "tm_create": "2024-01-17 10:32:00.000000",
    "tm_update": "2024-01-17 10:32:00.000000",
    "tm_delete": ""
}

Type

Message type indicates whether it’s a regular message or system notification.

Type	Description
normal	Regular message sent by an agent.
system	System-generated notification message.

Threading

Messages can form conversation threads by specifying a parent message ID. When a message includes a parent_id, it appears as a reply to the parent message, creating a nested conversation structure within the talk.

Threading Rules:

Parent message must exist in the same talk.
Parent message can be deleted (soft delete) - the thread structure is preserved.
Replies can have their own replies, creating multi-level threads.

Reactions

Agents can add emoji reactions to messages. Reactions are stored in the message metadata and include:

emoji: The emoji character (e.g., “👍”, “❤️”, “😊”).
owner_type: Type of the reactor (e.g., “agent”).
owner_id: Unique identifier of the agent who reacted.
tm_create: Timestamp when the reaction was added.

Multiple agents can react to the same message, and the same agent can add multiple different emoji reactions. Reactions provide quick feedback without sending a full message response.

Participant

{
    "id": "<string>",
    "customer_id": "<string>",
    "owner_type": "<string>",
    "owner_id": "<string>",
    "chat_id": "<string>",
    "tm_joined": "<string>"
}

id: Participant’s unique identifier.
customer_id: Customer’s unique identifier.
owner_type: Type of the participant (e.g., “agent”).
owner_id: Participant’s unique identifier.
chat_id: Talk’s unique identifier that this participant belongs to.
tm_joined: Timestamp when the participant joined the talk.

Example

{
    "id": "f4d6e9b3-5c4a-4d5e-9f8a-2b3c4d5e6f7g",
    "customer_id": "5e4a0680-804e-11ec-8477-2fea5968d85b",
    "owner_type": "agent",
    "owner_id": "eb1ac5c0-ff63-47e2-bcdb-5da9c336eb4b",
    "chat_id": "e8b2e976-f043-44c8-bb89-e214e225e813",
    "tm_joined": "2024-01-17 10:30:00.000000"
}

Participant Management

Participants can be added to or removed from talks dynamically. When a participant is removed and later re-added, their join timestamp is updated to reflect the most recent join time.

Participant Rules:

Each talk can have multiple participants.
The same agent cannot be added as a participant twice (enforced by unique constraint).
When a participant is removed, they are hard-deleted from the database.
Re-adding a participant creates a new record with a new join timestamp.
Only participants of a talk can view messages and send new messages.

Permissions:

Participants can view all messages in the talk.
Participants can send messages to the talk.
Participants can add reactions to any message in the talk.
Non-participants cannot access talk messages or send messages.

Tutorial

This tutorial demonstrates how to use the Talk API to create conversations, manage participants, send messages with threading and reactions.

Create a Talk

Create a new talk conversation:

POST /service_agents/talk_chats
{
    "type": "normal"
}

Response:

{
    "id": "e8b2e976-f043-44c8-bb89-e214e225e813",
    "customer_id": "5e4a0680-804e-11ec-8477-2fea5968d85b",
    "type": "normal",
    "tm_create": "2024-01-17 10:30:00.000000",
    "tm_update": "2024-01-17 10:30:00.000000",
    "tm_delete": ""
}

Add Participants

Add agents to the talk:

POST /service_agents/talk_chats/e8b2e976-f043-44c8-bb89-e214e225e813/participants
{
    "owner_type": "agent",
    "owner_id": "47fe0b7c-7333-46cf-8b23-61e14e62490a"
}

Response:

{
    "id": "f4d6e9b3-5c4a-4d5e-9f8a-2b3c4d5e6f7g",
    "customer_id": "5e4a0680-804e-11ec-8477-2fea5968d85b",
    "owner_type": "agent",
    "owner_id": "47fe0b7c-7333-46cf-8b23-61e14e62490a",
    "chat_id": "e8b2e976-f043-44c8-bb89-e214e225e813",
    "tm_joined": "2024-01-17 10:31:00.000000"
}

Send a Message

Send a message to the talk:

POST /service_agents/talk_messages
{
    "chat_id": "e8b2e976-f043-44c8-bb89-e214e225e813",
    "type": "normal",
    "text": "Hello team! Let's discuss the new feature."
}

Response:

{
    "id": "a3c5e8f2-4d3a-4b5c-9e7f-1a2b3c4d5e6f",
    "customer_id": "5e4a0680-804e-11ec-8477-2fea5968d85b",
    "owner_type": "agent",
    "owner_id": "eb1ac5c0-ff63-47e2-bcdb-5da9c336eb4b",
    "chat_id": "e8b2e976-f043-44c8-bb89-e214e225e813",
    "type": "normal",
    "text": "Hello team! Let's discuss the new feature.",
    "medias": [],
    "metadata": {
        "reactions": []
    },
    "tm_create": "2024-01-17 10:32:00.000000",
    "tm_update": "2024-01-17 10:32:00.000000",
    "tm_delete": ""
}

Reply to a Message (Threading)

Reply to an existing message by specifying the parent_id:

POST /service_agents/talk_messages
{
    "chat_id": "e8b2e976-f043-44c8-bb89-e214e225e813",
    "parent_id": "a3c5e8f2-4d3a-4b5c-9e7f-1a2b3c4d5e6f",
    "type": "normal",
    "text": "Great idea! I'll start working on the requirements."
}

Response:

{
    "id": "b2d4f7a1-3c2e-4f5a-8d9c-2e3f4a5b6c7d",
    "customer_id": "5e4a0680-804e-11ec-8477-2fea5968d85b",
    "owner_type": "agent",
    "owner_id": "47fe0b7c-7333-46cf-8b23-61e14e62490a",
    "chat_id": "e8b2e976-f043-44c8-bb89-e214e225e813",
    "parent_id": "a3c5e8f2-4d3a-4b5c-9e7f-1a2b3c4d5e6f",
    "type": "normal",
    "text": "Great idea! I'll start working on the requirements.",
    "medias": [],
    "metadata": {
        "reactions": []
    },
    "tm_create": "2024-01-17 10:33:00.000000",
    "tm_update": "2024-01-17 10:33:00.000000",
    "tm_delete": ""
}

Add a Reaction

Add an emoji reaction to a message:

POST /service_agents/talk_messages/b2d4f7a1-3c2e-4f5a-8d9c-2e3f4a5b6c7d/reactions
{
    "emoji": "👍"
}

Response:

{
    "id": "b2d4f7a1-3c2e-4f5a-8d9c-2e3f4a5b6c7d",
    "customer_id": "5e4a0680-804e-11ec-8477-2fea5968d85b",
    "owner_type": "agent",
    "owner_id": "47fe0b7c-7333-46cf-8b23-61e14e62490a",
    "chat_id": "e8b2e976-f043-44c8-bb89-e214e225e813",
    "parent_id": "a3c5e8f2-4d3a-4b5c-9e7f-1a2b3c4d5e6f",
    "type": "normal",
    "text": "Great idea! I'll start working on the requirements.",
    "medias": [],
    "metadata": {
        "reactions": [
            {
                "emoji": "👍",
                "owner_type": "agent",
                "owner_id": "eb1ac5c0-ff63-47e2-bcdb-5da9c336eb4b",
                "tm_create": "2024-01-17 10:34:00.000000"
            }
        ]
    },
    "tm_create": "2024-01-17 10:33:00.000000",
    "tm_update": "2024-01-17 10:34:00.000000",
    "tm_delete": ""
}

List Messages

Retrieve messages from a talk with pagination:

GET /service_agents/talk_messages?page_size=50

Response:

{
    "result": [
        {
            "id": "a3c5e8f2-4d3a-4b5c-9e7f-1a2b3c4d5e6f",
            "customer_id": "5e4a0680-804e-11ec-8477-2fea5968d85b",
            "owner_type": "agent",
            "owner_id": "eb1ac5c0-ff63-47e2-bcdb-5da9c336eb4b",
            "chat_id": "e8b2e976-f043-44c8-bb89-e214e225e813",
            "type": "normal",
            "text": "Hello team! Let's discuss the new feature.",
            "medias": [],
            "metadata": {
                "reactions": []
            },
            "tm_create": "2024-01-17 10:32:00.000000",
            "tm_update": "2024-01-17 10:32:00.000000",
            "tm_delete": ""
        },
        {
            "id": "b2d4f7a1-3c2e-4f5a-8d9c-2e3f4a5b6c7d",
            "customer_id": "5e4a0680-804e-11ec-8477-2fea5968d85b",
            "owner_type": "agent",
            "owner_id": "47fe0b7c-7333-46cf-8b23-61e14e62490a",
            "chat_id": "e8b2e976-f043-44c8-bb89-e214e225e813",
            "parent_id": "a3c5e8f2-4d3a-4b5c-9e7f-1a2b3c4d5e6f",
            "type": "normal",
            "text": "Great idea! I'll start working on the requirements.",
            "medias": [],
            "metadata": {
                "reactions": [
                    {
                        "emoji": "👍",
                        "owner_type": "agent",
                        "owner_id": "eb1ac5c0-ff63-47e2-bcdb-5da9c336eb4b",
                        "tm_create": "2024-01-17 10:34:00.000000"
                    }
                ]
            },
            "tm_create": "2024-01-17 10:33:00.000000",
            "tm_update": "2024-01-17 10:34:00.000000",
            "tm_delete": ""
        }
    ],
    "next_page_token": "2024-01-17 10:33:00.000000"
}

Remove a Participant

Remove a participant from the talk:

DELETE /service_agents/talk_chats/e8b2e976-f043-44c8-bb89-e214e225e813/participants/f4d6e9b3-5c4a-4d5e-9f8a-2b3c4d5e6f7g

Response:

{
    "id": "f4d6e9b3-5c4a-4d5e-9f8a-2b3c4d5e6f7g",
    "customer_id": "5e4a0680-804e-11ec-8477-2fea5968d85b",
    "owner_type": "agent",
    "owner_id": "47fe0b7c-7333-46cf-8b23-61e14e62490a",
    "chat_id": "e8b2e976-f043-44c8-bb89-e214e225e813",
    "tm_joined": "2024-01-17 10:31:00.000000"
}

Delete a Talk

Delete a talk (soft delete):

DELETE /service_agents/talk_chats/e8b2e976-f043-44c8-bb89-e214e225e813

Response:

{
    "id": "e8b2e976-f043-44c8-bb89-e214e225e813",
    "customer_id": "5e4a0680-804e-11ec-8477-2fea5968d85b",
    "type": "normal",
    "tm_create": "2024-01-17 10:30:00.000000",
    "tm_update": "2024-01-17 10:35:00.000000",
    "tm_delete": "2024-01-17 10:35:00.000000"
}

Talk

Overview

How Talk Works

Talk Types

Talk Lifecycle

Creating and Managing Talks

Sending Messages

Message Threading

Message Reactions

Message Types

Real-Time Updates

Common Scenarios

Best Practices

Troubleshooting

Related Documentation

Talk

Talk

Example

Type

Message

Message

Example

Type

Threading

Reactions

Participant

Participant

Example

Participant Management

Tutorial

Create a Talk

Add Participants

Send a Message

Reply to a Message (Threading)

Add a Reaction

List Messages

Remove a Participant

Delete a Talk