Message Events
Voicetta sends SMS and WhatsApp activity through two events.
Use them when your product needs to know what is happening in a conversation.
| Event | Fires for |
|---|---|
message.received | A customer message and the reply generated by Voicetta |
message.sent | A message Voicetta sends without an incoming customer message |
For the finished conversation and its evaluation, use thread.completed.
Why there are two events
An incoming message and an outgoing message are different events.
When a customer sends a message, Voicetta creates a message.received event.
If the assistant replies in the same turn, that reply is included in the reply field.
When Voicetta starts the conversation itself, it creates a message.sent event.
That can happen when the voice assistant sends a confirmation during a call or when a follow-up is sent.
message.received
{
"event": "message.received",
"event_id": "b71e9d02-4a6c-4f18-9d3e-7c2b5a4e8f31",
"version": 1,
"occurred_at": "2026-08-20T14:12:00+00:00",
"message": {
"message_id": "b71e9d02-4a6c-4f18-9d3e-7c2b5a4e8f31",
"workspace_id": "2a1f8e7d-4c3b-4a29-9f18-6d5e4c3b2a19",
"assistant_id": "7c6b5a49-3e2d-4c1b-8a97-5f4e3d2c1b09",
"assistant_name": "Front Desk",
"channel": "whatsapp",
"direction": "inbound",
"thread_id": "c82fa013-5b7d-4029-8e4f-8d3c6b5f9a42",
"source": "inbound",
"occurred_at": "2026-08-20T14:12:00+00:00",
"content": "Do you have a room free on Friday?",
"provider_message_id": "SM8f3c1a2b4d5e6f70",
"reply": {
"content": "Yes, we have a double available. Shall I hold it?",
"provider_message_id": "SM1a2b3c4d5e6f7080",
"timestamp": "2026-08-20T14:12:04+00:00"
},
"customer": {
"customer_id": "5d4c3b2a-1f09-4e8d-7c6b-5a493e2d1c0b",
"name": "Jane Texter",
"phone": "+15551234567"
}
}
}message.sent
{
"event": "message.sent",
"event_id": "d93ba124-6e8f-4130-9a5f-9e4d7c6b0a53",
"version": 1,
"occurred_at": "2026-08-20T10:03:12+00:00",
"message": {
"message_id": "d93ba124-6e8f-4130-9a5f-9e4d7c6b0a53",
"workspace_id": "2a1f8e7d-4c3b-4a29-9f18-6d5e4c3b2a19",
"assistant_id": "7c6b5a49-3e2d-4c1b-8a97-5f4e3d2c1b09",
"assistant_name": "Front Desk",
"channel": "sms",
"direction": "outbound",
"thread_id": "e04cb235-7f90-4241-8b60-af5e8d7c1b64",
"source": "voice_tool",
"occurred_at": "2026-08-20T10:03:12+00:00",
"content": "Your booking reference is BK-4471. See you Friday.",
"provider_message_id": "SM2b3c4d5e6f708190",
"customer": {
"customer_id": "5d4c3b2a-1f09-4e8d-7c6b-5a493e2d1c0b",
"phone": "+15551234567"
}
}
}Reading the fields
contentis the message text.channelissmsorwhatsapp.directionisinboundoroutbound.thread_ididentifies the conversation.provider_message_idis the carrier's message id when available.replyappears onmessage.receivedwhen the assistant replies in the same turn.
source
| Value | Meaning |
|---|---|
inbound | Customer started the conversation |
voice_tool | Voice assistant sent the message during a call |
evaluation_follow_up | Recovery follow-up after evaluation |
test | Dashboard test message |
Test messages are not delivered to production webhooks or returned by the read API.
Treat unknown future source values as unknown origins, not errors.
Timing
Messages are usually delivered within 15–30 seconds.
They are not guaranteed to arrive in order.
If order matters, sort by occurred_at.
Costs
If you enable the costs block, messages can include an indicative message cost.
This is not the billed amount.
Use your invoice as the source of truth for billing.
What messages do not contain
A single message does not contain:
- a conversation summary
- evaluation results
- a recording
- call latency
- assistant configuration
Use thread.completed for the finished conversation.
Reading messages through the API
GET /v1/messagesYou can filter by date, assistant, channel, direction, and thread_id.
Use the API when you need history or when you need to recover messages your webhook did not receive.