whatsapp.call.connect

Use whatsapp.call.connect to handle this event at your webhook endpoint.

Triggers

Occurs when an incoming call provides an SDP offer or a business-initiated call provides an SDP answer. Subscribe to whatsapp.call.connect when you configure your webhook endpoint. Use sdpType to distinguish an offer from an answer. For an incoming offer, create an SDP answer before accepting the call.

Syntax

YCloud sends an HTTP POST request to your configured webhook URL. The following shape shows one payload variant. Angle-bracket values are placeholders; their types are listed under Parameters. Optional fields and other variants are described below.

{
  "id": "<ID>",
  "type": "whatsapp.call.connect",
  "apiVersion": "<API_VERSION>",
  "createTime": "<CREATE_TIME>",
  "callingConnect": {
    "id": "<ID>",
    "wacid": "<WACID>",
    "phoneId": "<PHONE_ID>",
    "from": "<FROM>",
    "to": "<TO>",
    "direction": "<DIRECTION>",
    "dialTime": "<DIAL_TIME_VALUE>",
    "sdpType": "<SDP_TYPE>",
    "sdp": "<SDP>"
  }
}

Parameters

Validate the YCloud-Signature HTTP header before you process the JSON body. See signature validation.

Event envelope

Parameter	Type	Required	Description
`id`	string	Yes	Unique ID for the event. Minimum length: `6`. Maximum length: `128`.
`type`	string	Yes	Always `whatsapp.call.connect`.
`apiVersion`	string	Yes	The API version used to render this event.
`createTime`	string (date-time)	Yes	The time at which this event was created, formatted in RFC 3339. e.g., `2022-06-01T12:00:00.000Z`.

Event payload

Parameter	Type	Required	Description
`callingConnect`	object	No	Event-specific `callingConnect` payload.

The four common envelope fields are required. Payload fields depend on the event variant. In each object table, Required applies when its parent object is present. Optional fields can be omitted; a sample does not make a field required.

callingConnect

Parameter	Type	Required	Description
`id`	string	Yes	Unique ID for the call event.
`wacid`	string	Yes	The WhatsApp call ID. This ID uniquely identifies the call session.
`phoneId`	string	No	The WhatsApp Business phone number ID.
`from`	string	No	The caller’s phone number in E.164 format.
`fromUserId`	string	No	The caller’s WhatsApp Business-scoped user ID (BSUID) for customer-initiated calls.
`fromParentUserId`	string	No	The caller’s parent WhatsApp Business-scoped user ID for customer-initiated calls.
`to`	string	No	The callee’s phone number in E.164 format.
`toUserId`	string	No	The callee’s WhatsApp Business-scoped user ID (BSUID) for business-initiated calls.
`toParentUserId`	string	No	The callee’s parent WhatsApp Business-scoped user ID for business-initiated calls.
`customerProfile`	object	No	The customer’s profile information, including WhatsApp username when available.
`direction`	string	No	The direction of the call. `USER_INITIATED`: Call initiated by the customer to the business. `BUSINESS_INITIATED`: Call initiated by the business to the customer.
`sdpType`	string	No	The SDP type for the WebRTC connection. Values: `offer`, `answer`.
`sdp`	string	No	The Session Description Protocol (SDP) information compliant with RFC 8866. Contains media session parameters for the WebRTC connection.
`dialTime`	integer (int64)	No	The time when the call was dialed, in Unix timestamp milliseconds.

callingConnect.customerProfile

Parameter	Type	Required	Description
`name`	string	No	Name of the WhatsApp account.
`username`	string	No	WhatsApp username.

Example

The following JSON is the body delivered to your receiver. IDs, phone numbers, and other account values are illustrative.

WhatsApp call connect event

Example payload when a WhatsApp call is connected

{
  "id": "evt_call_connect_123",
  "type": "whatsapp.call.connect",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "callingConnect": {
    "id": "6757b723960b25543b9ecc66",
    "wacid": "wacid.HBgNNjI4MTM2MTkwNTEzMxUCABIYIEF",
    "phoneId": "461269257068832",
    "from": "+12025550124",
    "to": "+12025550123",
    "direction": "USER_INITIATED",
    "dialTime": 1733826430000,
    "sdpType": "offer",
    "sdp": "v=0\r\no=- 1732169627243 2 IN IP4 127.0.0.1\r\ns=-\r\nt=0 0\r\na=group:BUNDLE audio\r\na=msid-semantic: WMS af3b01e3-eb42-4244-812e-db903c062ae7\r\na=ice-lite\r\nm=audio 3480 UDP/TLS/RTP/SAVPF 111 126\r\nc=IN IP4 31.13.87.130\r\na=rtcp:9 IN IP4 0.0.0.0\r\na=candidate:785588535 1 udp 2122260223 31.13.87.130 3480 typ host generation 0 network-cost 50\r\na=candidate:1906600321 1 udp 2122262783 2a03:2880:f217:d0:face:b00c:0:699c 3480 typ host generation 0 network-cost 50\r\na=ice-ufrag:CvRXRnInnWhQzLIE\r\na=ice-pwd:HGXUGAFI8wK6seuVknBT2Q==\r\na=fingerprint:sha-256 FB:56:A1:C5:37:35:6C:5C:1B:05:23:B0:DD:BB:2E:C9:5F:E4:70:61:7B:D9:1D:09:84:76:46:23:12:38:B7:01\r\na=setup:actpass\r\na=mid:audio\r\na=sendrecv\r\na=msid:af3b01e3-eb42-4244-812e-db903c062ae7 WhatsAppTrack1\r\na=rtcp-mux\r\na=rtpmap:111 opus/48000/2\r\na=rtcp-fb:111 transport-cc\r\na=fmtp:111 maxaveragebitrate=20000;maxplaybackrate=16000;minptime=20;sprop-maxcapturerate=16000;useinbandfec=1\r\na=rtpmap:126 telephone-event/8000\r\na=maxptime:20\r\na=ptime:20\r\na=ssrc:659928310 cname:WhatsAppAudioStream1\r\n"
  }
}

User-initiated Calling Connect

{
  "id": "evt_6757b723a5a42d369ef48480",
  "type": "whatsapp.call.connect",
  "apiVersion": "v2",
  "createTime": "2024-12-10T03:36:03.749Z",
  "callingConnect": {
    "id": "6757b723960b25543b9ecc66",
    "wacid": "wacid.HBgNNjI4MTM2MTkwNTEzMxrtLopSdPMwd",
    "phoneId": "461269257068832",
    "from": "+12025550124",
    "fromUserId": "ID.13491208655302741918",
    "fromParentUserId": "ID.11815799212886844830",
    "to": "+12025550123",
    "direction": "USER_INITIATED",
    "sdpType": "offer",
    "sdp": "<<RFC 4566 SDP>>"
  }
}

Business-initiated Calling Connect

{
  "id": "evt_676e5a0d7a9cb742d02d7645",
  "type": "whatsapp.call.connect",
  "apiVersion": "v2",
  "createTime": "2024-12-27T07:41:01.554Z",
  "callingConnect": {
    "id": "676e5a0d94c533526d3c5ad5",
    "wacid": "wacid.HBgNNjI4MTM2MTkwNTEzMxUCABE",
    "phoneId": "461269257068832",
    "from": "+12025550124",
    "to": "+12025550123",
    "toUserId": "ID.13491208655302741918",
    "toParentUserId": "ID.11815799212886844830",
    "direction": "BUSINESS_INITIATED",
    "sdpType": "answer",
    "sdp": "<<RFC 4566 SDP>>",
    "dialTime": 1735283452000
  }
}

After verifying the signature and durably accepting the event, return a 2xx response. Process slow work asynchronously.

HTTP/1.1 200 OK

For scenario walkthroughs, see annotated examples.

Getting Started

Guides

Endpoints

Webhook reference

whatsapp.call.connect

Triggers

Syntax

Parameters

Event envelope

Event payload

callingConnect

Example

​Triggers

​Syntax

​Parameters

​Event envelope

​Event payload

​callingConnect

​Example

Triggers

Syntax

Parameters

Event envelope

Event payload

callingConnect

Example