Messages
Send messages to active conversations via the Virbe API.
Sending Messages Programmatically
Use the Messages endpoint to send messages into an active conversation on behalf of an external system.
Create Message
POST /api/v1/conversations/:id/messages/add
Send a new message to an active conversation.
Path Parameters
- id – the conversation's unique identifier (UUID)
Request Body
The request body has the following top-level fields:
| Field | Type | Required | Description |
|---|---|---|---|
senderId | string | yes | A string of your choice that identifies the source of the message (e.g. "operator-panel", "crm-integration") |
action | object | yes | The message action to perform (see Message Action Schema) |
senderType | string | no | Type of sender (e.g. "EndUser", "User", "Api") |
replyTo | string | no | UUID of the message this is replying to |
The action object describes what kind of message to send. The most common action types are:
- text – send a text message:
{ "text": { "text": "Your message" } } - customAction – trigger a named action:
{ "customAction": { "name": "welcome" } } - uiAction – display interactive UI elements (buttons, cards, web views)
Sending a Text Message
curl -X POST \
"https://my-assistant.virbe.app/api/v1/conversations/CONVERSATION_ID/messages/add" \
-H "x-virbe-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"senderId": "operator-panel",
"action": {
"text": { "text": "The operator says hello!" }
}
}'Triggering a Named Action
curl -X POST \
"https://my-assistant.virbe.app/api/v1/conversations/CONVERSATION_ID/messages/add" \
-H "x-virbe-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"senderId": "operator-panel",
"action": {
"customAction": { "name": "welcome" }
}
}'This endpoint requires an API key with the ConversationActions scope.
You can only send messages to conversations that are currently active. Sending a message to a closed conversation will return a 409 Conflict error.