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).

NumberFieldJSON nameTypeKindWhat it is
1event_ideventIdstringsingleThe 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.
2channelchannelChannelsingleThe network the event happened on. Part of the event ID.
3accountaccountstringsingleThe 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.
4conversation_idconversationIdstringsingleThe 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.
5directiondirectionDirectionsingleWho started the event, seen from the account. Part of the event ID.
6source_message_idsourceMessageIdstringsingleThe 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.
7occurred_at_unix_msoccurredAtUnixMsint64singleWhen it happened, by the source's clock, in UTC milliseconds. Timelines and metrics are ordered by this time (ING-8).
8captured_at_unix_mscapturedAtUnixMsint64singleWhen the device app read it from the source, by its own clock, in UTC milliseconds.
9source_sequencesourceSequenceint64singleThe 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.
10sendersenderstringsingleThe 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.
11languagelanguagestringsingleThe language of the content as a BCP 47 tag (he, en, th), or empty when the device app does not know it.
20texttextTextBodyone of bodyA text message.
21voice_notevoiceNoteVoiceNoteBodyone of bodyA recorded voice message. Its audio is attached with RegisterMedia.
22filefileFileBodyone of bodyA file: an image, a video, a document. Its bytes are attached with RegisterMedia.
23callcallCallBodyone of bodyA call. Its recording, when there is one, is attached with RegisterMedia.
24editeditEditBodyone of bodyA change to the text of an earlier message.
25deletedeleteDeleteBodyone of bodyThe removal of an earlier message.
26reactionreactionReactionBodyone of bodyAn emoji reaction to an earlier message, or its removal.

TextBody

TextBody is a text message.

NumberFieldJSON nameTypeKindWhat it is
1texttextstringsingleThe message text, as the source holds it.

VoiceNoteBody

VoiceNoteBody is a recorded voice message.

NumberFieldJSON nameTypeKindWhat it is
1duration_msdurationMsint64singleIts length in milliseconds, as the source reports it.

FileBody

FileBody is a file sent in a conversation.

NumberFieldJSON nameTypeKindWhat it is
1file_namefileNamestringsingleThe file name shown to the people in the chat, when there is one.
2mime_typemimeTypestringsingleThe media type, such as image/jpeg or application/pdf.
3captioncaptionstringsingleThe text sent with the file, when there is one.

CallBody

CallBody is a voice or video call.

NumberFieldJSON nameTypeKindWhat it is
1duration_msdurationMsint64singleHow long the call was connected, in milliseconds. 0 for a call nobody answered.
2answeredansweredboolsingleTrue when the call was connected; false for a missed or declined call.
3videovideoboolsingleTrue 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.

NumberFieldJSON nameTypeKindWhat it is
1target_event_idtargetEventIdstringsingleThe event_id of the message that was edited.
2new_textnewTextstringsingleThe text after the edit.

DeleteBody

DeleteBody records that an earlier message was removed for everyone.

NumberFieldJSON nameTypeKindWhat it is
1target_event_idtargetEventIdstringsingleThe event_id of the message that was removed.

ReactionBody

ReactionBody records an emoji reaction to an earlier message.

NumberFieldJSON nameTypeKindWhat it is
1target_event_idtargetEventIdstringsingleThe event_id of the message reacted to.
2emojiemojistringsingleThe 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.

NumberNameWhat it means
0CHANNEL_UNSPECIFIEDNot set. The server refuses an event without a channel.
1CHANNEL_WHATSAPPWhatsApp: chats, groups, voice notes, files and WhatsApp calls.
2CHANNEL_PHONEAn 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).

NumberNameWhat it means
0DIRECTION_UNSPECIFIEDNot set. The server refuses an event without a direction.
1DIRECTION_INBOUNDSomeone else sent it to the account: a received message, an incoming call.
2DIRECTION_OUTBOUNDThe account sent it: a sent message, an outgoing call.