Jodie - AI Answering Service

Event: New WhatsApp Conversation

This event is fired whenever a WhatsApp conversation handled by your Jodie AI agent is closed and analysed. It is the WhatsApp analogue of the New Call event and provides the complete conversation, including the full message thread and any data that was collected.

The event fires once the conversation reaches its CLOSED state (after the closing job has run data extraction), so the payload always contains the final close_reason, every message, and all collected data.

It is delivered through the exact same infrastructure as the new_call event: the same Account-Id header, the same Signature HMAC (verify it with your existing webhook signing secret), and the same retry and backoff behaviour. Any endpoint already receiving new_call can branch on event_type and start consuming this event with no other changes.

Payload Structure

The webhook payload is a JSON object with the following structure:

KeyTypeDescription
event_typestringEvent type identifier. Always "new_whatsapp_conversation".
conversation_idstringThe unique identifier for the conversation (prefixed with wac_).
contact_phone_numberstring | nullThe phone number of the contact, in E.164 format, or null if unavailable.
timestampstring | nullAn ISO 8601 formatted timestamp indicating when the conversation was first seen.
start_timestring | nullAn ISO 8601 formatted timestamp of the first message in the conversation.
end_timestring | nullAn ISO 8601 formatted timestamp of the last message in the conversation.
message_countintegerThe total number of messages in the conversation.
close_reasonstring | nullA short human-readable reason describing why the conversation was closed.
data_collectionsarrayAn array of objects representing data collected during the conversation. Empty array [] if none.
messagesarrayAn array of message objects, ordered chronologically. Empty array [] if there are no messages.

The data_collections Object

Each object in the data_collections array has the following structure:

KeyTypeDescription
keystringThe name of the data point that was collected.
valuestring | nullThe value that was collected for the specified key.

The messages Object

Each object in the messages array has the following structure:

KeyTypeDescription
orderintegerSequential position in the conversation (1, 2, 3...).
directionstringThe direction of the message. Either "inbound" (from the contact) or "outbound" (from your business).
sent_bystring | nullWho sent an outbound message: "ai" (Jodie), or "company" (a team member typed it on their own device). null for inbound messages.
messagestringThe message text. An empty string "" if the message has no text body.
sent_atstring | nullAn ISO 8601 formatted timestamp indicating when the message was sent.

Example Payload

Here is an example of the JSON payload you can expect to receive for a new_whatsapp_conversation event.

{
  "event_type": "new_whatsapp_conversation",
  "conversation_id": "wac_a1b2c3d4e5f6g7h8i9j0",
  "contact_phone_number": "+447123456789",
  "timestamp": "2026-06-24T10:00:00Z",
  "start_time": "2026-06-24T10:00:05Z",
  "end_time": "2026-06-24T10:04:30Z",
  "message_count": 3,
  "close_reason": "Customer query resolved",
  "data_collections": [
    {
      "key": "customer_name",
      "value": "Jane Doe"
    }
  ],
  "messages": [
    { "order": 1, "direction": "inbound", "sent_by": null, "message": "Hi, are you open today?", "sent_at": "2026-06-24T10:00:05Z" },
    { "order": 2, "direction": "outbound", "sent_by": "ai", "message": "Yes, we're open until 6pm.", "sent_at": "2026-06-24T10:00:12Z" },
    { "order": 3, "direction": "outbound", "sent_by": "company", "message": "See you soon!", "sent_at": "2026-06-24T10:04:30Z" }
  ]
}