Concepts

Chat ids and phone numbers

Messages are addressed with a chat id, not a plain phone number. For a person it is the number in international format, without a plus or spaces, followed by @c.us.

Tusk WhatsApp API: Chat ids and phone numbers

What do chat ids look like?

Person
[email protected] for +254 700 000 002.
Group
[email protected]. Group ids come from the groups endpoints.

The chat list endpoint reports a kind for every chat: individual, group, channel, status, broadcast or unknown.

How do I check that a number is on WhatsApp?

Call GET /sessions/{sessionId}/contacts/check/{number} with the number in international format, without a plus. The response includes exists and the chat_id to use (null when the number is not on WhatsApp). Checks are limited to 30 per minute per session.

curl "https://api.tuskmail.africa/v1/whatsapp/sessions/$SESSION_ID/contacts/check/254700000002" \
  -H "X-API-Key: $TUSK_WA_KEY"
200 OK
{
  "number": "254700000002",
  "exists": true,
  "chat_id": "[email protected]"
}