Message Action Schema
Complete reference for all action types available when sending messages via the Virbe API.
When sending a message via POST /api/v1/conversations/:id/messages/add, the request body has this structure:
{
"senderId": "...",
"senderType": "...",
"replyTo": "...",
"action": {
"text": { ... },
"customAction": { ... },
"variableStore": { ... },
"uiAction": { ... },
"behaviorAction": { ... }
}
}| Field | Type | Required | Description |
|---|---|---|---|
senderId | string | yes | A string of your choice that identifies the source of the message (e.g. "operator-panel") |
action | object | yes | The action to perform – see below |
senderType | string | no | Type of sender (e.g. "EndUser", "User", "Api") |
replyTo | string (UUID) | no | ID of the message this is replying to |
The action object can include one or more action types simultaneously. All action fields are optional – include only the types you need.
Text Action
Send a text message to the conversation. The virtual being will process this as user input.
| Field | Type | Required | Description |
|---|---|---|---|
text | string | yes | The message text |
raw | string | no | Raw/unprocessed version of the text |
html | string | no | HTML-formatted version |
ssml | string | no | SSML markup for speech synthesis |
language | string | no | Language code (e.g. en-US) |
{
"senderId": "operator-panel",
"action": {
"text": {
"text": "Hello from the operator!",
"language": "en-US"
}
}
}Custom Action
Trigger a named custom action. Use this for application-specific actions like navigation commands or feature triggers.
| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | Action name |
value | any | no | Optional payload of any type |
{
"senderId": "operator-panel",
"action": {
"customAction": {
"name": "navigate",
"value": { "screen": "product-details", "id": 42 }
}
}
}Variable Store
Set a key-value pair on the conversation. Variables are persisted and accessible in conversation flows.
| Field | Type | Required | Description |
|---|---|---|---|
key | string | yes | Variable name |
value | any | yes | Variable value (any type) |
{
"senderId": "operator-panel",
"action": {
"variableStore": {
"key": "operatorName",
"value": "John"
}
}
}UI Action
Display interactive UI elements to the end user – buttons, cards, input fields, or web views. This is the most feature-rich action type.
The UI action always uses the envelope format:
{
"senderId": "operator-panel",
"action": {
"uiAction": {
"name": "virbe-payload-v3",
"value": {
"type": "buttons | cards | input | webView",
"timeoutMs": 10000,
...
}
}
}
}| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | Always "virbe-payload-v3" |
value.type | string | no | UI type: buttons, cards, or webView |
value.timeoutMs | number | no | Auto-dismiss timeout in milliseconds (default: 10000) |
Buttons
Show a set of quick-reply buttons. When the user taps a button, its id is sent back as input.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | Unique button identifier (sent back on click) |
label | string | yes | Button display text |
{
"senderId": "operator-panel",
"action": {
"uiAction": {
"name": "virbe-payload-v3",
"value": {
"type": "buttons",
"timeoutMs": 15000,
"buttons": [
{ "id": "yes", "label": "Yes, please" },
{ "id": "no", "label": "No, thanks" },
{ "id": "more", "label": "Tell me more" }
]
}
}
}
}Cards
Show a set of rich cards with optional images. Each card can trigger either a text response or a signal when selected.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | Unique card identifier |
title | string | no | Card title |
imageUrl | string | no | URL of the card image |
payloadType | string | yes | What happens on selection: "text" or "signal" |
text | string | no | Text sent back when payloadType is "text" |
signal | object | no | Signal triggered when payloadType is "signal" (see Signal) |
{
"senderId": "operator-panel",
"action": {
"uiAction": {
"name": "virbe-payload-v3",
"value": {
"type": "cards",
"timeoutMs": 20000,
"cards": [
{
"id": "product-a",
"title": "Product A",
"imageUrl": "https://example.com/product-a.jpg",
"payloadType": "text",
"text": "I want Product A"
},
{
"id": "product-b",
"title": "Product B",
"imageUrl": "https://example.com/product-b.jpg",
"payloadType": "signal",
"signal": { "name": "select-product", "value": "b" }
}
]
}
}
}
}Web View
Open a web page or render custom HTML inside the conversation UI. Ideal for forms, maps, or embedded content.
| Field | Type | Required | Description |
|---|---|---|---|
type | string | no | "URL" to load a URL, or "HTML" to render inline HTML (default: "URL") |
url | string | no | URL to load (when type is "URL") |
html | string | no | HTML content to render (when type is "HTML") |
fullscreen | boolean | no | Show in fullscreen mode |
transparent | boolean | no | Transparent background |
closeAfterInactivity | boolean | no | Auto-close after inactivity (default: true) |
closeAfterInactivityTimeout | number | no | Inactivity timeout in milliseconds |
closeOnOutsideClick | boolean | no | Close when user clicks outside (default: false) |
showCloseButton | boolean | no | Show a close button |
allowRedirect | boolean | no | Allow navigation within the web view (default: false) |
disableKeyboard | boolean | no | Disable keyboard input in the web view (default: false) |
overrideSettings | boolean | no | Override default web view settings (default: false) |
{
"senderId": "operator-panel",
"action": {
"uiAction": {
"name": "virbe-payload-v3",
"value": {
"type": "webView",
"webView": {
"type": "URL",
"url": "https://example.com/feedback-form",
"fullscreen": false,
"showCloseButton": true,
"closeOnOutsideClick": true,
"allowRedirect": false
}
}
}
}
}Inline HTML example:
{
"senderId": "operator-panel",
"action": {
"uiAction": {
"name": "virbe-payload-v3",
"value": {
"type": "webView",
"webView": {
"type": "HTML",
"html": "<div style='padding:20px'><h2>Welcome!</h2><p>Custom content here.</p></div>",
"fullscreen": false,
"showCloseButton": true
}
}
}
}
}Behavior Action
Trigger animations and emotions on the virtual being. Controls gestures and facial expressions with precise timing.
The behavior action uses the same envelope format as UI actions:
| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | Always "virbe-payload-v3" |
value.gestures | array | yes | List of gesture animations |
value.emotions | array | yes | List of emotion animations |
Each animation object:
| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | Animation name |
start | number | yes | Start time in seconds |
duration | number | no | Duration in seconds |
{
"senderId": "operator-panel",
"action": {
"behaviorAction": {
"name": "virbe-payload-v3",
"value": {
"gestures": [
{ "name": "wave", "start": 0, "duration": 2.5 }
],
"emotions": [
{ "name": "happy", "start": 0, "duration": 3.0 }
]
}
}
}
}