Get a Call by ID

GET /calls/{CallID}

Use this method to retrieve the latest available information about a WhatsApp call, including its status, timestamps, direction, and participants. The method returns call information currently available on the connected channel. It does not request call history directly from WhatsApp servers.

Request

GET https://gate.whapi.cloud/calls/{CallID}
Authorization: Bearer <CHANNEL_TOKEN>

CallID is the call identifier received in a calls.post webhook event. The request does not require a body.

Example

curl 'https://gate.whapi.cloud/calls/0068351C4D056D46D8152E64E7F5E5DB' \
  -H 'Authorization: Bearer <CHANNEL_TOKEN>'

Response

A successful request returns 200 OK:

{
    "id": "00D675F8E3D4904D0CE521883F18438D",
    "timestamp": 1787578687000,
    "result": "accepted_elsewhere",
    "started_at": 1787578672000,
    "answered_at": 1787578687000,
    "finalized": true,
    "group_call": false,
    "video_call": false,
    "offline_call": false,
    "participants": [],
    "status": "ended",
    "direction": "incoming",
    "from": "919984351847",
    "chat_id": "[e-mail]"
}

The most important fields are:

Field	Description
status	Current lifecycle status: initiated, ringing, answered, ended, missed, or canceled.
result	Detailed call outcome, such as connected, missed, rejected, or accepted_elsewhere.
finalized	Indicates whether the call reached a terminal state on the linked device.
participants	Call participants and their individual outcomes.

Timestamps are returned in Unix milliseconds.

You can use the timestamp fields to calculate the call timing:

• started_at — when the call started;

• answered_at — when the call was answered;

Please note: WhatsApp does not provide full call duration details through the linked device session.

After a call ends, detailed call information remains local to the device where the call was answered or made. For example, the phone may show the call duration, while a linked web or desktop session may only show that the call was answered on another device.

Because of this limitation, the API cannot reliably retrieve the exact call end time or calculate the final call duration directly.

Receiving Call Updates via Webhooks

Call information can also be received in real time through webhooks.

You can configure this through channel settings or with the "Update channel settings" method.

Configure a webhook subscription for the calls.post event:

{
  "url": "https://example.com/webhooks/whatsapp",
  "mode": "body",
  "events": [
    {
      "type": "calls",
      "method": "post"
    }
  ]
}

Each webhook contains a calls array with the latest call state. Store the call id to retrieve or refresh its information later using GET /calls/{CallID}.

Errors

Status	Description
401	Missing or invalid channel token.
404	The call was not found in the channel’s retained data.
500	Internal server error.