Skip to content

WhatsApp VoIP Calls#

Beta version

The functionality is in beta mode. Features are subject to change and may also work unstably.

For questions about connecting to the plan and additional terms, please email support@green-api.com or write to the chat on the website.

The "Calls" plan provides a universal REST API for managing incoming and outgoing WhatsApp calls.

Contents#

  1. Features
  2. Instance authorization for the Calls plan
  3. Quick start with calls
    3.1. Outgoing call scenario
    3.2. Incoming call scenario
  4. Call management methods
    4.1 Call control
    4.2 Call signaling
  5. Browser library and ready-made example

1. Features#

The plan allows you to make and receive calls with WhatsApp users. A single call lasts no longer than 90 minutes.

2. Instance authorization for the Calls plan#

To work with the Calls plan, the instance must be authorized. The instance is authorized in the console by scanning the QR code with the WhatsApp Business or WhatsApp mobile application.

3. Quick start with calls#

Audio is transmitted using WebRTC technology, and everything that happens to the call is reported by the callsRtc connection. That is why both scenarios start the same way: the connection is opened first and kept open for the entire call.

The call state arrives in this connection in a message of type state and takes the values idle (no call), inc-call (an incoming call has arrived), out-call (an outgoing call is in progress) and on-call (the conversation is in progress).

3.1. Outgoing call scenario#

  1. Open the callsRtc connection.
  2. Start the call with the callsDial method, specifying the chat ID of the other party. A 200 OK response with the call ID means that the command has been accepted; dialing is indicated by the state changing to out-call.
  3. Get the list of servers with the callsGetIceServers method and send an audio offer in the connection — a message of type offer. Send it only after the callsDial method has completed.
  4. Wait for the server response in the connection — a message of type answer — and exchange messages of type ice-candidate. After that, audio is transmitted in both directions.
  5. When the other party accepts the call, the state changes to on-call.
  6. End the call with the callsHangUp method. The call is over when the state has changed to idle; in the same message the server may specify the reason in the reason field.

3.2. Incoming call scenario#

  1. Open the callsRtc connection.
  2. An incoming call is indicated by the inc-call state. Information about the caller is in the info object: the ID of the other party and, if WhatsApp provided it, the name.
  3. Accept the call with the callsAccept method or reject it with the callsReject method. The server marks the start of the conversation by changing the state to on-call.
  4. After accepting the call, get the list of servers with the callsGetIceServers method and send an audio offer — a message of type offer. For an incoming call, the offer is also created by your application, not by the server.
  5. Wait for a message of type answer and exchange messages of type ice-candidate. After that, audio is transmitted in both directions.
  6. End the call with the callsHangUp method — the state will change to idle.

4. Call management methods#

4.1 Call control#

4.2 Call signaling#

  • CallsRtc — Call state and audio transmission

5. Browser library and ready-made example#

If you need calls in a browser, everything described above is already implemented in the @green-api/whatsapp-api-calls-client-js library: it maintains the CallsRtc connection, calls the call control methods and transmits audio over WebRTC.