Events and enums
The event every call carries, its kinds of content, and the lists of named values the fields use.
This page is made from the API contract, contract/schema/namjai/v1/event.proto, so it always says what the server really accepts. How to reach the server and what a failure looks like are on Server API.
Messages
Each message is a JSON object, or protobuf. A field's JSON name is the name to use in JSON; the server also accepts the field name. A field left out reads as empty, zero or false.
Event
Event is one thing that happened in a conversation, exactly as one device app captured it: a text, a voice note, a file or a call. An edit, a delete or a reaction is an event of its own that points at the original.
Identity: event_id is a hash of channel, account, conversation_id, direction and source_message_id, computed with contract/event-id-format. The same message captured twice always has the same ID, which is what makes resending harmless (see IngestService.SendBatch).
Times: every time is a UTC instant in milliseconds since 1970-01-01. The device app converts the source's own clock before sending (WhatsApp on iPhone and Mac counts seconds from 2001).
| Number | Field | JSON name | Type | Kind | What it is |
|---|---|---|---|---|---|
| 1 | event_id | eventId | string | single | The event's ID, computed by the device app with contract/event-id-format from the five identity fields below. The server computes it again and refuses the batch when the two differ, so a device app with a wrong rule fails loudly. |
| 2 | channel | channel | Channel | single | The network the event happened on. Part of the event ID. |
| 3 | account | account | string | single | The agent's own handle on that channel: the phone number in E.164 (+999812345678) for WhatsApp and phone. It is part of the event ID. |
| 4 | conversation_id | conversationId | string | single | The source's own ID for the conversation: the WhatsApp chat ID (a contact's or a group's JID), or the other party's number in E.164 for a phone line. Part of the event ID. |
| 5 | direction | direction | Direction | single | Who started the event, seen from the account. Part of the event ID. |
| 6 | source_message_id | sourceMessageId | string | single | The source's own ID for this message, unchanged. For a call it is the source's call ID, or a stand-in when the source has none: see contract/event-id-format.CallSourceID. Part of the event ID. |
| 7 | occurred_at_unix_ms | occurredAtUnixMs | int64 | single | When it happened, by the source's clock, in UTC milliseconds. Timelines and metrics are ordered by this time (ING-8). |
| 8 | captured_at_unix_ms | capturedAtUnixMs | int64 | single | When the device app read it from the source, by its own clock, in UTC milliseconds. |
| 9 | source_sequence | sourceSequence | int64 | single | The source's own ordering number for the message inside the conversation, when it has one (WhatsApp's row order). 0 means none. It breaks ties between events that happened in the same millisecond. |
| 10 | sender | sender | string | single | The handle of whoever sent it, in E.164 for a phone number. Needed in groups; in a direct chat it is the account or the other party. |
| 11 | language | language | string | single | The language of the content as a BCP 47 tag (he, en, th), or empty when the device app does not know it. |
| 20 | text | text | TextBody | one of body | A text message. |
| 21 | voice_note | voiceNote | VoiceNoteBody | one of body | A recorded voice message. Its audio is attached with RegisterMedia. |
| 22 | file | file | FileBody | one of body | A file: an image, a video, a document. Its bytes are attached with RegisterMedia. |
| 23 | call | call | CallBody | one of body | A call. Its recording, when there is one, is attached with RegisterMedia. |
| 24 | edit | edit | EditBody | one of body | A change to the text of an earlier message. |
| 25 | delete | delete | DeleteBody | one of body | The removal of an earlier message. |
| 26 | reaction | reaction | ReactionBody | one of body | An emoji reaction to an earlier message, or its removal. |
TextBody
TextBody is a text message.
| Number | Field | JSON name | Type | Kind | What it is |
|---|---|---|---|---|---|
| 1 | text | text | string | single | The message text, as the source holds it. |
VoiceNoteBody
VoiceNoteBody is a recorded voice message.
| Number | Field | JSON name | Type | Kind | What it is |
|---|---|---|---|---|---|
| 1 | duration_ms | durationMs | int64 | single | Its length in milliseconds, as the source reports it. |
FileBody
FileBody is a file sent in a conversation.
| Number | Field | JSON name | Type | Kind | What it is |
|---|---|---|---|---|---|
| 1 | file_name | fileName | string | single | The file name shown to the people in the chat, when there is one. |
| 2 | mime_type | mimeType | string | single | The media type, such as image/jpeg or application/pdf. |
| 3 | caption | caption | string | single | The text sent with the file, when there is one. |
CallBody
CallBody is a voice or video call.
| Number | Field | JSON name | Type | Kind | What it is |
|---|---|---|---|---|---|
| 1 | duration_ms | durationMs | int64 | single | How long the call was connected, in milliseconds. 0 for a call nobody answered. |
| 2 | answered | answered | bool | single | True when the call was connected; false for a missed or declined call. |
| 3 | video | video | bool | single | True for a video call. |
EditBody
EditBody replaces the text of an earlier message. The original event keeps its own content; readers apply the edits in order.
| Number | Field | JSON name | Type | Kind | What it is |
|---|---|---|---|---|---|
| 1 | target_event_id | targetEventId | string | single | The event_id of the message that was edited. |
| 2 | new_text | newText | string | single | The text after the edit. |
DeleteBody
DeleteBody records that an earlier message was removed for everyone.
| Number | Field | JSON name | Type | Kind | What it is |
|---|---|---|---|---|---|
| 1 | target_event_id | targetEventId | string | single | The event_id of the message that was removed. |
ReactionBody
ReactionBody records an emoji reaction to an earlier message.
| Number | Field | JSON name | Type | Kind | What it is |
|---|---|---|---|---|---|
| 1 | target_event_id | targetEventId | string | single | The event_id of the message reacted to. |
| 2 | emoji | emoji | string | single | The emoji. Empty means the sender removed their reaction. |
Enums
An enum is a list of named values. In JSON send the name, such as CHANNEL_WHATSAPP; in protobuf, the number.
Channel
Channel is the network a conversation happens on. The value's name, not its number, is part of every event ID (see contract/event-id-format), so a name is never changed once released.
| Number | Name | What it means |
|---|---|---|
| 0 | CHANNEL_UNSPECIFIED | Not set. The server refuses an event without a channel. |
| 1 | CHANNEL_WHATSAPP | WhatsApp: chats, groups, voice notes, files and WhatsApp calls. |
| 2 | CHANNEL_PHONE | An ordinary phone line: cellular or desk phone calls. |
Direction
Direction says who started an event, seen from the account that captured it. The value's name is part of every event ID (see contract/event-id-format).
| Number | Name | What it means |
|---|---|---|
| 0 | DIRECTION_UNSPECIFIED | Not set. The server refuses an event without a direction. |
| 1 | DIRECTION_INBOUND | Someone else sent it to the account: a received message, an incoming call. |
| 2 | DIRECTION_OUTBOUND | The account sent it: a sent message, an outgoing call. |