Overview

Note

AI Context

• Complexity: Low

• Cost: Free – Talk messaging does not incur per-message charges.

• Async: No. POST https://api.voipbin.net/v1.0/service_agents/talk_chats and POST https://api.voipbin.net/v1.0/service_agents/talk_messages return synchronously with the created resource. Real-time delivery to other participants is handled via WebSocket push events.

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

Chat Types

VoIPBin supports different chat types for various communication needs.

Chat Type Values

Type	Description
direct	1:1 Direct Message – private between two users
group	Group Direct Message – private multi-user chat, invite-only
talk	Public Open Channel – topic-based, searchable (e.g., #general)

Direct Chat (1:1)

Private conversation between two agents.

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

Group Chat

Multi-participant conversation for team discussions.

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

Chat Lifecycle

Chats are created and managed through the Talk API. Participants can be added and removed.

Note

AI Implementation Hint

The Talk API uses /service_agents/talk_chats for chat management and /service_agents/talk_messages for messaging. The owner_id for participants must be a valid agent UUID obtained from GET https://api.voipbin.net/v1.0/agents. Only agents who are participants of a chat can send or view messages.

Chat Flow

POST /service_agents/talk_chats
          |
          v
   +------------+
   |   Chat     |
   |  created   |
   +-----+------+
         |
         v
  Add participants,
  send messages,
  manage threads

Participant Management

POST /service_agents/talk_chats/{id}/participants
          |
          v
   +------------+
   | Participant|
   |   added    |
   +-----+------+
         |
         | DELETE /service_agents/talk_chats/{id}/participants/{pid}
         v
   +------------+
   | Participant|
   |  removed   |
   +------------+

Creating and Managing Chats

Create chats and manage participants through the Talk API.

Create a Chat

$ curl -X POST 'https://api.voipbin.net/v1.0/service_agents/talk_chats?token=<token>' \
    --header 'Content-Type: application/json' \
    --data '{
        "type": "group",
        "name": "Project Discussion",
        "participants": [
            {
                "owner_type": "agent",
                "owner_id": "agent-uuid-1"
            },
            {
                "owner_type": "agent",
                "owner_id": "agent-uuid-2"
            }
        ]
    }'

Add Participant

$ curl -X POST 'https://api.voipbin.net/v1.0/service_agents/talk_chats/<chat-id>/participants?token=<token>' \
    --header 'Content-Type: application/json' \
    --data '{
        "owner_type": "agent",
        "owner_id": "agent-uuid-3"
    }'

Remove Participant

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

Discovering and Joining Public Channels

Public talk type chats (e.g., #general) work differently from direct and group chats: any agent in the customer can discover and join them without an invitation.

List Public Channels

GET /service_agents/talk_channels returns every public talk type channel for the customer, regardless of whether the requesting agent has joined it. This differs from GET /service_agents/talk_chats, which only returns chats the agent already participates in.

$ curl -X GET 'https://api.voipbin.net/v1.0/service_agents/talk_channels?token=<token>'

Join a Public Channel

POST /service_agents/talk_chats/{id}/join adds the authenticated agent as a participant of a talk type chat in a single call, without needing to know another participant’s ID. This endpoint only works for talk type chats; use the participants endpoint above for direct/group chats.

$ curl -X POST 'https://api.voipbin.net/v1.0/service_agents/talk_chats/<chat-id>/join?token=<token>'

Mentions

A message can mention an agent by writing [@display name](mention:<agent-id>) in its text. When the message is created, the server records the mention of every agent written this way, so an agent can list the messages that mention it across all of its chats.

GET /service_agents/talk_mentions returns the messages that mention the calling agent, from every chat the agent can access, newest first. The result uses the same message object as GET /service_agents/talk_messages and is paginated with page_size and page_token. An agent can only list its own mentions.

$ curl -X GET 'https://api.voipbin.net/v1.0/service_agents/talk_mentions?token=<token>&page_size=20'

{
    "result": [
        {
            "id": "93d48228-3ed7-11ef-a9ca-070e7ba46a55",
            "customer_id": "550e8400-e29b-41d4-a716-446655440000",
            "owner_type": "agent",
            "owner_id": "2a2ec0ba-8004-11ec-aea5-439829c92a7c",
            "chat_id": "e66d1da0-3ed7-11ef-9208-4bcc069917a1",
            "type": "normal",
            "text": "Please review this [@Alice](mention:6a1b3c5d-7e9f-4a2b-8c4d-0e1f2a3b4c5d)",
            "medias": [],
            "metadata": {"reactions": []},
            "tm_create": "2026-11-02T09:15:30.123456Z",
            "tm_update": "2026-11-02T09:15:30.123456Z",
            "tm_delete": null
        }
    ],
    "next_page_token": "2026-11-02T09:15:30.123456Z"
}

Rules:

• Only the mentions of agents are recorded. A mention of a contact (mention:contact:<id>) is not.

• A message records each mentioned agent once, in order of appearance, up to 50 distinct agents. Mentioning yourself is not recorded.

• system type messages are not scanned for mentions.

• The server does not check that the mentioned id belongs to an agent of the same customer; the list is always scoped to the calling agent and its customer, so it is never exposed to anyone else.

• Messages that were created before this feature was deployed are not listed. Mentions are not added to existing messages.

• A message in a direct or group chat that the calling agent is not a participant of, a deleted message and a message of a deleted chat are not returned. If the agent leaves a chat the mentions of that chat disappear from the list, and they come back when the agent joins again.

• Reading the list does not mark anything as read; read and unread state is not part of this endpoint.

Sending Messages

Send messages within talks with support for threading and media.

Send a Message

Agent                                   VoIPBin              Other Participants
   |                                       |                        |
   | POST /service_agents/talk_messages    |                        |
   +-------------------------------------->|                        |
   |                                       | Broadcast via WebSocket|
   |                                       +----------------------->|
   |  message_id                           |                        |
   |<--------------------------------------+                        |
   |                                       |                        |

Basic Message Example:

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

Reply to Message (Threading):

$ curl -X POST 'https://api.voipbin.net/v1.0/service_agents/talk_messages?token=<token>' \
    --header 'Content-Type: application/json' \
    --data '{
        "chat_id": "<chat-id>",
        "type": "normal",
        "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/service_agents/talk_messages?token=<token>' \
    --header 'Content-Type: application/json' \
    --data '{
        "chat_id": "<chat-id>",
        "type": "normal",
        "text": "Here is the design document.",
        "medias": [
            {
                "type": "file",
                "file_id": "<file-uuid>"
            }
        ]
    }'

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/service_agents/talk_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

Pinned Chats and Messages

An agent can pin a chat or a message to keep it at hand. A pin is personal to the agent who created it; other participants do not see it.

Pin a chat or a message

$ curl -X POST 'https://api.voipbin.net/v1.0/service_agents/talk_pins?token=<token>' \
    --header 'Content-Type: application/json' \
    --data '{
        "target_type": "message",
        "target_id": "<message-id>"
    }'

Rules

• target_type is chat or message. The agent must be able to access the chat (a participant of a direct or group chat).

• Pinning a target that is already pinned returns the existing pin.

• GET /service_agents/talk_pins lists the agent’s own pins, newest first. The optional target_type and chat_id query parameters narrow the list. A pin of a message carries the message in message.

• A pin is listed only while the agent can see its target. If the agent leaves a direct or group chat, its pins are hidden and they are listed again when the agent joins the chat again. A pin of a deleted chat or of a deleted message is not listed.

• DELETE /service_agents/talk_pins/{id} removes a pin. The pin of another agent is reported as not found.

See Pin for the response fields.

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     |
   +----------------------------->|
   |                              |
   |<==== chatmessage_created ====|
   |<==== chat_created ===========|
   |<==== chatparticipant_added ==|
   |                              |

Event Types

Event	When it fires
chat_created	New chat session created
chat_updated	Chat session details updated
chat_deleted	Chat session deleted
chatmessage_created	New message sent to chat
chatmessage_deleted	Message removed from chat
chatmessage_reaction_updated	Reaction added or removed on a message
chatparticipant_added	Participant joined the chat
chatparticipant_removed	Participant left the chat

Common Scenarios

Scenario 1: Team Project Discussion

Create a group talk for project collaboration.

1. Create chat with team members
   POST /service_agents/talk_chats
   { "type": "group", "name": "Q1 Project", "participants": [...] }

2. Send updates as messages
   POST /service_agents/talk_messages
   { "chat_id": "<chat-id>", "type": "normal", "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

Related Documentation

• Agent Overview - Agent management

• WebSocket Overview - Real-time connections

• Conversation Overview - Multi-channel messaging