What is the exact payload structure for every MyOperator Webhook v2 event?

What is the exact payload structure for every MyOperator Webhook v2 event?

⚡Quick answer -

Every Webhook v2 delivery contains a 12-field root envelope followed by an event-specific payload object.

• Common envelope fields = event_id, company_id, event_type, event_sequence, event_version, timestamp, channel, direction, session_id, system_identifier, customer_identifier, payload.

• Six Call sub-events and eight WhatsApp sub-events each have their own payload schema (see tables below). For full JSON examples, open the official Postman collections (links below).

When should I use this guide?

Read on when you need to:

• Map Webhook v2 fields into a CRM/warehouse without opening Postman.

• Debug “missing field” queries from Support or customers.

• Explain edge-cases such as system_identifier = null or event_sequence not present.



1. Postman collections (full JSON)

Event channel

Share-with-developer URL

Call events

https://documenter.getpostman.com/view/38426694/2sAXqy3evq#34994bec-7a73-49a8-8db6-00c6a5ac5998

WhatsApp events

https://documenter.getpostman.com/view/38426694/2sAXqy3evq#02a13792-e0ca-409d-9b47-7806ad268469

Tip: never paste large payloads in email; send the collection link instead.



2. Root envelope (present in every event)

Field

Type

What it means

Gotcha/note

event_id

string

Unique identifier; use for deduplication.

Always check before processing retry deliveries.

company_id

string

Your MyOperator account ID.

—

event_type

string

What happened (e.g., call.initiated).

Full list below.

event_sequence

integer

Order inside a session.

Absent on call.disposition.

event_version

integer

Schema version (currently 1).

May increment on breaking change.

timestamp

datetime

When MyOperator sent the event (ISO-8601).

Send-time, not generate-time.

channel

string

call or WhatsApp

Route to the right handler.

direction

string

incoming/outgoing / ""

Empty string for conversation.* events.

session_id

string

Correlates all events in one call/chat.

Use to stitch timeline.

system_identifier

string

DID (call) or phone_number_id (WhatsApp).

null on call.summary by design.

customer_identifier

string

Customer phone (E.164).

Best-effort for some international numbers.

payload

object

Event-specific fields.

See next sections.



3. Call-event payload reference (6 sub-events)

event_type

UI sub-event

Key payload fields

Important notes

call.initiated

Start of the call

started_at

Minimal; grab system_identifier (DID) here.

call.dial_begin

Start dialing

legs[ ] – leg_index, type, phone_number, result, dept_id, started_at

Fires per dial attempt; result = dialing.

call.answered

Call responded

legs[ ] – dial_status: ANSWER, answered_at, ring_duration, talk_duration

Only answered leg updates.

call.end

Call ended

id, category, status, duration, billable, recording_filename, ref_id, client_ref_id, obd_campaign, legs[ ]

dept_id is plain string; no agent names.

call.summary

Call summary

legs[ ] with agent{uuid,name,email,contact,extension}, department{id,name}, comments[ ]

system_identifier = null; fires after call.end.

call.disposition

Call disposition

dispositions[ ] – type,name,user_id,added_at; comments[ ] – id,content,posted_at,posted_by

Stand-alone; no event_sequence; can arrive any time post-call



4. WhatsApp-event payload reference (8 sub-events)

(direction = "" for conversation events)

event_type

UI sub-event

Key payload fields

Important notes

message.sent

Message sent

id, message_by, action: outgoing, status: sent, data.type, events[ ], metadata.myop_ref_id, source

source values: lc / cmp / api (see §6).

message.received

Message received

id, action: incoming, message_by: null, status: received, data.context.body, conversation{ }

message_by always null (customer sender).

message.delivered

Message delivered

id, status: delivered, events[delivered].timestamp

Partial payload—status only.

message.read

Message read

id, status: read, is_read: true, events[ ] (all set)

Check is_read flag.

message.failed

Message failed

id, status: failed, metadata.errors{ } (WhatsApp code map)

errors object contains WA error details.

message.link_tracking

Track URL clicked

link_tracking{template_id, template_name, button_info, clicked_at}, data.type: template

link_tracking is top-level, not in data.

conversation.assign

Conversation assigned

conversation{ id, customer_contact, assigned_to, status, expire_at }, activity{ action_by, action_to }

Non-directional; direction = "".

conversation.close

Conversation closed

conversation{ status: closed, expire_at }, activity{ action_by, action_to: null }

action_to is null on close.



5. Complete event_type → UI mapping

Channel

event_type

Admin-panel sub-event

call

call.initiated

Start of the call

call

call.dial_begin

Start dialing

call

call.answered

Call responded

call

call.end

Call ended

call

call.summary

Call summary

call

call.disposition

Call disposition

whatsapp

message.sent

Message sent

whatsapp

message.received

Message received

whatsapp

message.delivered

Message delivered

whatsapp

message.read

Message read

whatsapp

message.failed

Message failed

whatsapp

message.link_tracking

Track URL clicked

whatsapp

conversation.assign

Conversation assigned

whatsapp

conversation.close

Conversation closed



6. WhatsApp source field reference

source

Origin

myop_ref_id value

lc

Live Chat (agent panel)

Populated UUID

cmp

Campaign (bulk send)

"" (empty string)

api

API (programmatic)

null

Avoid using myop_ref_id to detect origin—always rely on source.



7. Integration best-practice checklist

  1. Respond with HTTP 200 immediately; queue heavy work async.
  2. Deduplicate using event_id.
  3. Use event_sequence to reorder call events (not present on call.disposition).
  4. Correlate events with session_id for the full timeline.
  5. Capture system_identifier from call.initiated (null on call.summary).
  6. Differentiate WhatsApp origin via source (lc / cmp / api).
  7. Expect E.164 customer numbers; parse defensively.