Send WhatsApp messages from your code

Thirteen endpoints, one job each: text, media (by URL or upload), location, contacts, polls, stickers, reactions, edits, group invites, events, marking messages read, and forwarding. Every request needs an API key — create one in API Keys.

Want to try requests without writing code first? Use the API Playground.

API Keys API Playground

Authentication

Send your API key on every request as a header:

bash

X-API-Key: YOUR_API_KEY

POST/integrations-user/whatsapp/send-message(no /api prefix)

Send Message

Send a plain text message to a WhatsApp number through one of your connected sessions.

Field	Type	Required	Description
to	string	REQUIRED	Recipient WhatsApp number, digits only with country code (e.g. "971509876543"). No "+" or leading "00".
message	string	REQUIRED	Text content to send.
mentions	string[]	OPTIONAL	Group chats only — phone numbers or JIDs to @-mention. No-op in a 1:1 chat.
sessionId	number	OPTIONAL	Specific WhatsApp session ID to send from. Takes priority over phoneNumber when both are given.
phoneNumber	string	OPTIONAL	Your connected session’s phone number, used to pick which session sends the message when your account has more than one connected. Ignored if sessionId is given. If neither is given, the first connected session is used.

447700900123

Hello from the API!

now ✓✓

bash

curl -X POST 'https://api.chatpingo.com/integrations-user/whatsapp/send-message' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "to": "12025550147", "message": "Hello from the API!", "sessionId": null, "phoneNumber": "447476686841" }'

POST/integrations-user/whatsapp/send-media(no /api prefix)

Send Media (by URL)

Send media (image, video, document, or audio) to a WhatsApp number through one of your connected sessions, by linking to a publicly reachable URL.

Field	Type	Required	Description
to	string	REQUIRED	Recipient WhatsApp number, digits only with country code (e.g. "971509876543"). No "+" or leading "00".
media	object (JSON)	REQUIRED	Shape: { url?, base64?, mimetype (required), fileName?, caption?, viewOnce? } — provide either url or base64. Images/videos only — viewOnce lets the recipient open it once before it disappears.
sessionId	number	OPTIONAL	Specific WhatsApp session ID to send from. Takes priority over phoneNumber when both are given.
phoneNumber	string	OPTIONAL	Your connected session’s phone number, used to pick which session sends the message when your account has more than one connected. Ignored if sessionId is given. If neither is given, the first connected session is used.

447700900123

🖼image attachment

Check out this image

now ✓✓

bash

curl -X POST 'https://api.chatpingo.com/integrations-user/whatsapp/send-media' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "to": "12025550147", "media": { "url": "https://www.tropicaltickets.com/cdn/shop/files/download_72.jpg?v=1691659648", "mimetype": "image/jpeg", "fileName": "photo.jpg", "caption": "Check out this image" }, "sessionId": null, "phoneNumber": "447476686841" }'

POST/integrations-user/whatsapp/send-media(no /api prefix)

Send Media (Upload File)

Same endpoint as "Send Media (by URL)". This example shows sending a file straight from your device: switch to the Form tab, click the 📎 attach icon on the "media" row, and pick a file — it's base64-encoded automatically into the shape the API expects.

Field	Type	Required	Description
to	string	REQUIRED	Recipient WhatsApp number, digits only with country code (e.g. "971509876543"). No "+" or leading "00".
media	object (JSON)	REQUIRED	Attach a file via the Form tab's 📎 icon instead of typing this by hand. Shape once attached: { base64, mimetype, fileName }. Add "viewOnce": true (images/videos only) to make it disappear after the recipient opens it once.
sessionId	number	OPTIONAL	Specific WhatsApp session ID to send from. Takes priority over phoneNumber when both are given.
phoneNumber	string	OPTIONAL	Your connected session’s phone number, used to pick which session sends the message when your account has more than one connected. Ignored if sessionId is given. If neither is given, the first connected session is used.

447700900123

🖼image attachment

Check out this image

now ✓✓

bash

curl -X POST 'https://api.chatpingo.com/integrations-user/whatsapp/send-media' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "to": "12025550147", "media": { "caption": "Check out this image" }, "sessionId": null, "phoneNumber": "447476686841" }'

POST/integrations-user/whatsapp/send-location(no /api prefix)

Send Location

Send a pinned location to a WhatsApp number through one of your connected sessions.

Field	Type	Required	Description
to	string	REQUIRED	Recipient WhatsApp number, digits only with country code (e.g. "971509876543"). No "+" or leading "00".
latitude	number	REQUIRED	Degrees latitude, between -90 and 90.
longitude	number	REQUIRED	Degrees longitude, between -180 and 180.
name	string	OPTIONAL	Label shown above the pin (e.g. a venue name).
address	string	OPTIONAL	Address text shown under the pin.
sessionId	number	OPTIONAL	Specific WhatsApp session ID to send from. Takes priority over phoneNumber when both are given.
phoneNumber	string	OPTIONAL	Your connected session’s phone number, used to pick which session sends the message when your account has more than one connected. Ignored if sessionId is given. If neither is given, the first connected session is used.

447700900123

📍

ChatPingo HQ

Dubai, UAE

now ✓✓

bash

curl -X POST 'https://api.chatpingo.com/integrations-user/whatsapp/send-location' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "to": "12025550147", "latitude": 25.2048, "longitude": 55.2708, "name": "ChatPingo HQ", "address": "Dubai, UAE", "sessionId": null, "phoneNumber": "447476686841" }'

POST/integrations-user/whatsapp/send-contact(no /api prefix)

Send Contact

Send one or more contact cards (vCards) to a WhatsApp number through one of your connected sessions.

Field	Type	Required	Description
to	string	REQUIRED	Recipient WhatsApp number, digits only with country code (e.g. "971509876543"). No "+" or leading "00".
contacts	array of { name, phone }	REQUIRED	One or more contact cards to send — at least one required. Each needs a display name and phone number.
sessionId	number	OPTIONAL	Specific WhatsApp session ID to send from. Takes priority over phoneNumber when both are given.
phoneNumber	string	OPTIONAL	Your connected session’s phone number, used to pick which session sends the message when your account has more than one connected. Ignored if sessionId is given. If neither is given, the first connected session is used.

447700900123

Jane Doe

+971 50 987 6543

now ✓✓

bash

curl -X POST 'https://api.chatpingo.com/integrations-user/whatsapp/send-contact' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "to": "12025550147", "contacts": [ { "name": "Jane Doe", "phone": "971509876543" } ], "sessionId": null, "phoneNumber": "447476686841" }'

POST/integrations-user/whatsapp/send-poll(no /api prefix)

Send Poll

Send a poll with a question and 2–12 selectable options to a WhatsApp number through one of your connected sessions.

Field	Type	Required	Description
to	string	REQUIRED	Recipient WhatsApp number, digits only with country code (e.g. "971509876543"). No "+" or leading "00".
question	string	REQUIRED	The poll question.
options	string[]	REQUIRED	2 to 12 selectable options.
selectableCount	number	OPTIONAL	How many options a voter can pick. Defaults to 1 (single choice) — set higher to allow multiple.
mentions	string[]	OPTIONAL	Group chats only — phone numbers or JIDs to @-mention. No-op in a 1:1 chat.
sessionId	number	OPTIONAL	Specific WhatsApp session ID to send from. Takes priority over phoneNumber when both are given.
phoneNumber	string	OPTIONAL	Your connected session’s phone number, used to pick which session sends the message when your account has more than one connected. Ignored if sessionId is given. If neither is given, the first connected session is used.

447700900123

📊 What's your favorite color?

Red

Blue

Green

now ✓✓

bash

curl -X POST 'https://api.chatpingo.com/integrations-user/whatsapp/send-poll' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "to": "12025550147", "question": "What's your favorite color?", "options": [ "Red", "Blue", "Green" ], "selectableCount": 1, "sessionId": null, "phoneNumber": "447476686841" }'

POST/integrations-user/whatsapp/send-sticker(no /api prefix)

Send Sticker

Send an image as a WhatsApp sticker through one of your connected sessions. Non-webp images are converted automatically.

Field	Type	Required	Description
to	string	REQUIRED	Recipient WhatsApp number, digits only with country code (e.g. "971509876543"). No "+" or leading "00".
media	object (JSON)	REQUIRED	Shape: { url?, base64?, mimetype? } — provide either url or base64. Attach a file via the Form tab's 📎 icon, or paste a URL. Anything that isn't already image/webp is converted server-side.
sessionId	number	OPTIONAL	Specific WhatsApp session ID to send from. Takes priority over phoneNumber when both are given.
phoneNumber	string	OPTIONAL	Your connected session’s phone number, used to pick which session sends the message when your account has more than one connected. Ignored if sessionId is given. If neither is given, the first connected session is used.

447700900123

🖼️

now ✓✓

bash

curl -X POST 'https://api.chatpingo.com/integrations-user/whatsapp/send-sticker' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "to": "12025550147", "media": {}, "sessionId": null, "phoneNumber": "447476686841" }'

POST/integrations-user/whatsapp/send-reaction(no /api prefix)

Send Reaction

React to an existing message with an emoji. messageId, remoteJid, and fromMe identify the target message — you already have these from your inbound webhook payload for that message.

Field	Type	Required	Description
messageId	string	REQUIRED	The WhatsApp message ID being reacted to (from your webhook payload).
remoteJid	string	REQUIRED	The chat the message belongs to (from your webhook payload).
fromMe	boolean	REQUIRED	Whether that message was sent by you (true) or received from the other side (false).
emoji	string	REQUIRED	The reaction emoji, e.g. "👍". Send an empty string to remove a previously-set reaction.
sessionId	number	OPTIONAL	Specific WhatsApp session ID to send from. Takes priority over phoneNumber when both are given.
phoneNumber	string	OPTIONAL	Your connected session’s phone number, used to pick which session sends the reaction when your account has more than one connected. Ignored if sessionId is given. If neither is given, the first connected session is used.

447700900123

Hello from the API!

now ✓✓

👍

bash

curl -X POST 'https://api.chatpingo.com/integrations-user/whatsapp/send-reaction' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "messageId": "ABCD1234EF567890", "remoteJid": "12025550147@s.whatsapp.net", "fromMe": false, "emoji": "👍", "sessionId": null, "phoneNumber": "447476686841" }'

POST/integrations-user/whatsapp/send-edit-message(no /api prefix)

Edit Message

Edit a text message your session already sent. messageId and remoteJid identify it — you get these back in the "messageId" field of that message's send response. WhatsApp only allows editing within about 15 minutes of sending.

Field	Type	Required	Description
messageId	string	REQUIRED	The WhatsApp message ID of the message to edit — must be one your session sent (from that send's response).
remoteJid	string	REQUIRED	The chat the message belongs to.
newText	string	REQUIRED	The corrected text.
sessionId	number	OPTIONAL	Specific WhatsApp session ID to send from. Takes priority over phoneNumber when both are given.
phoneNumber	string	OPTIONAL	Your connected session’s phone number, used to pick which session sends from when your account has more than one connected. Ignored if sessionId is given. If neither is given, the first connected session is used.

447700900123

Corrected text!

Edited · now ✓✓

bash

curl -X POST 'https://api.chatpingo.com/integrations-user/whatsapp/send-edit-message' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "messageId": "ABCD1234EF567890", "remoteJid": "12025550147@s.whatsapp.net", "newText": "Corrected text!", "sessionId": null, "phoneNumber": "447476686841" }'

POST/integrations-user/whatsapp/send-group-invite(no /api prefix)

Send Group Invite

Send a rich "join this group" message with a live invite link. Your session must already be a member/admin of the group.

Field	Type	Required	Description
to	string	REQUIRED	Recipient WhatsApp number to send the invite message to.
groupJid	string	REQUIRED	The group's JID (e.g. "123456789@g.us"). Your session must already be a member/admin.
text	string	OPTIONAL	Optional message text shown alongside the invite. Defaults to "Join {group name}".
sessionId	number	OPTIONAL	Specific WhatsApp session ID to send from. Takes priority over phoneNumber when both are given.
phoneNumber	string	OPTIONAL	Your connected session’s phone number, used to pick which session sends from when your account has more than one connected. Ignored if sessionId is given. If neither is given, the first connected session is used.

447700900123

👥

Sales Team

Group invite

Join Sales Team

now ✓✓

bash

curl -X POST 'https://api.chatpingo.com/integrations-user/whatsapp/send-group-invite' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "to": "12025550147", "groupJid": "123456789@g.us", "sessionId": null, "phoneNumber": "447476686841" }'

POST/integrations-user/whatsapp/send-event(no /api prefix)

Send Event

Send a calendar-invite-style event message to a WhatsApp number through one of your connected sessions.

Field	Type	Required	Description
to	string	REQUIRED	Recipient WhatsApp number, digits only with country code (e.g. "971509876543"). No "+" or leading "00".
name	string	REQUIRED	The event name.
description	string	OPTIONAL	Event description.
startDate	string (ISO 8601)	REQUIRED	Start date/time, e.g. "2026-08-01T18:00:00Z".
endDate	string (ISO 8601)	OPTIONAL	End date/time. Omit for an open-ended event.
sessionId	number	OPTIONAL	Specific WhatsApp session ID to send from. Takes priority over phoneNumber when both are given.
phoneNumber	string	OPTIONAL	Your connected session’s phone number, used to pick which session sends the message when your account has more than one connected. Ignored if sessionId is given. If neither is given, the first connected session is used.

447700900123

📅

Launch Party

Aug 1, 6:00 PM

now ✓✓

bash

curl -X POST 'https://api.chatpingo.com/integrations-user/whatsapp/send-event' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "to": "12025550147", "name": "Launch Party", "description": "Come celebrate with us", "startDate": "2026-08-01T18:00:00Z", "endDate": "2026-08-01T20:00:00Z", "sessionId": null, "phoneNumber": "447476686841" }'

POST/integrations-user/whatsapp/mark-read(no /api prefix)

Mark as Read

Mark a message your session received as read — turns on the blue ticks. messageId and remoteJid come from your inbound webhook payload for that message.

Field	Type	Required	Description
messageId	string	REQUIRED	The WhatsApp message ID to mark read (from your webhook payload).
remoteJid	string	REQUIRED	The chat the message belongs to (from your webhook payload).
fromMe	boolean	REQUIRED	Whether that message was sent by you (true) or received (false — the usual case here).
sessionId	number	OPTIONAL	Specific WhatsApp session ID to act on. Takes priority over phoneNumber when both are given.
phoneNumber	string	OPTIONAL	Your connected session’s phone number, used to pick which session acts when your account has more than one connected. Ignored if sessionId is given. If neither is given, the first connected session is used.

447700900123

Hey, are we still on for tomorrow?

✓✓ Read

bash

curl -X POST 'https://api.chatpingo.com/integrations-user/whatsapp/mark-read' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "messageId": "ABCD1234EF567890", "remoteJid": "12025550147@s.whatsapp.net", "fromMe": false, "sessionId": null, "phoneNumber": "447476686841" }'

POST/integrations-user/whatsapp/forward-message(no /api prefix)

Forward Message

Re-sends the given text to a new recipient, marked "Forwarded" in the WhatsApp UI. This sends the text you provide — it doesn't replay an arbitrary original message you only have the ID of.

Field	Type	Required	Description
to	string	REQUIRED	Recipient WhatsApp number, digits only with country code (e.g. "971509876543"). No "+" or leading "00".
text	string	REQUIRED	The text content to forward.
sessionId	number	OPTIONAL	Specific WhatsApp session ID to send from. Takes priority over phoneNumber when both are given.
phoneNumber	string	OPTIONAL	Your connected session’s phone number, used to pick which session sends from when your account has more than one connected. Ignored if sessionId is given. If neither is given, the first connected session is used.

447700900123

↪ Forwarded

Forwarded content

now ✓✓

bash

curl -X POST 'https://api.chatpingo.com/integrations-user/whatsapp/forward-message' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "to": "12025550147", "text": "Forwarded content", "sessionId": null, "phoneNumber": "447476686841" }'

Errors

Every endpoint on this page returns the same status codes.

201	Created	Message accepted and sent.
400	Bad Request	The body failed validation — check the field table above.
401	Unauthorized	Missing or invalid API key.
429	Too Many Requests	Rate limit is 30 requests/minute per API key.
503	Service Unavailable	No connected WhatsApp session was available to send from.

Webhooks

Get incoming messages and session changes pushed to your server. Add a webhook URL to a session on the Webhooks page and pick the events it should receive. Leave the list empty to receive every event except opt-in ones.

ChatPingo sends each event as an HTTP POST with a JSON body (Content-Type: application/json). Reply with any 2xx status within 10 seconds. Failed deliveries are not retried automatically. You can inspect every delivery and re-send it from the dashboard.

Field	Type	Description
id	string	Unique id of this event (UUID). The same for every webhook of the session and for dashboard re-sends, so dedupe on it.
event	string	Event name, see the list below.
sessionId	number	The WhatsApp session the event is about.
data	object	Event-specific fields, documented per event below.
timestamp	string	When the event was sent, ISO 8601.

EVENTmessages.received

Message received

Someone sent a message to your WhatsApp number: a contact, or a member of a group the number is in.

data fields

Field	Type	Description
userId	number	Your ChatPingo account id.
sessionId	number	The WhatsApp session (number) this message belongs to.
phoneNumber	string	The session's own phone number.
messageId	string	WhatsApp message id. Use it with reactions, edits, mark-read and forward.
internalId	number	ChatPingo database id of the stored message.
from	string	Sender JID, e.g. 12025550147@s.whatsapp.net (a group JID ends in @g.us).
to	string	Recipient JID.
fromNumber	string	Sender phone number, digits only (omitted when not a phone JID).
toNumber	string	Recipient phone number, digits only (omitted when not a phone JID).
chatId	string	JID of the conversation: the contact or the group. Pass it as remoteJid to Send Reaction, Edit Message and Mark as Read.
chatNumber	string	Contact phone number for one-to-one chats (omitted for groups).
groupName	string \| null	Group subject, only present when isGroup is true.
content	string \| null	Text body, or the caption for media. null when there is none.
type	string	text, image, video, audio, document, sticker, contact or location.
mediaUrl	string	Download URL of the media file (media messages only).
mediaFileName	string	Original file name (media messages only).
mediaFileType	string	MIME type, e.g. image/jpeg (media messages only).
mediaFileSize	number	Size in bytes (media messages only).
isGroup	boolean	true when the chat is a group.
isBroadcast	boolean	true for broadcast lists and status updates.
isChannel	boolean	true for WhatsApp Channels (newsletters).
timestamp	string	When WhatsApp sent the message, ISO 8601.
timestampUnix	number	Same moment as Unix seconds.
quotedMessageId	string	Id of the message this one replies to (replies only).
forwarded	boolean	true when the message was forwarded.
participant	string	Context participant JID, e.g. the author of a quoted group message.
fromMe	boolean	false for received messages, true for sent ones.

Example POST body

json

{
  "id": "9b2f6c1e-4d7a-4e8b-a1f3-5c0d2e7b8a64",
  "event": "messages.received",
  "sessionId": 1,
  "data": {
    "userId": 42,
    "sessionId": 1,
    "phoneNumber": "447476686841",
    "messageId": "3EB0C431C26A1916E07E",
    "internalId": 98231,
    "from": "12025550147@s.whatsapp.net",
    "to": "447476686841@s.whatsapp.net",
    "fromNumber": "12025550147",
    "toNumber": "447476686841",
    "chatId": "12025550147@s.whatsapp.net",
    "chatNumber": "12025550147",
    "content": "Hi, is my order on the way?",
    "type": "text",
    "isGroup": false,
    "isBroadcast": false,
    "isChannel": false,
    "timestamp": "2026-10-12T09:41:07.000Z",
    "timestampUnix": 1791798067,
    "fromMe": false
  },
  "timestamp": "2026-10-12T09:42:15.512Z"
}

EVENTmessages.send

Message sent

Your number sent a message: through the API, the inbox, a campaign, an automation, or the phone itself. Same fields as messages.received, with fromMe: true.

data fields

Field	Type	Description
userId	number	Your ChatPingo account id.
sessionId	number	The WhatsApp session (number) this message belongs to.
phoneNumber	string	The session's own phone number.
messageId	string	WhatsApp message id. Use it with reactions, edits, mark-read and forward.
internalId	number	ChatPingo database id of the stored message.
from	string	Sender JID, e.g. 12025550147@s.whatsapp.net (a group JID ends in @g.us).
to	string	Recipient JID.
fromNumber	string	Sender phone number, digits only (omitted when not a phone JID).
toNumber	string	Recipient phone number, digits only (omitted when not a phone JID).
chatId	string	JID of the conversation: the contact or the group. Pass it as remoteJid to Send Reaction, Edit Message and Mark as Read.
chatNumber	string	Contact phone number for one-to-one chats (omitted for groups).
groupName	string \| null	Group subject, only present when isGroup is true.
content	string \| null	Text body, or the caption for media. null when there is none.
type	string	text, image, video, audio, document, sticker, contact or location.
mediaUrl	string	Download URL of the media file (media messages only).
mediaFileName	string	Original file name (media messages only).
mediaFileType	string	MIME type, e.g. image/jpeg (media messages only).
mediaFileSize	number	Size in bytes (media messages only).
isGroup	boolean	true when the chat is a group.
isBroadcast	boolean	true for broadcast lists and status updates.
isChannel	boolean	true for WhatsApp Channels (newsletters).
timestamp	string	When WhatsApp sent the message, ISO 8601.
timestampUnix	number	Same moment as Unix seconds.
quotedMessageId	string	Id of the message this one replies to (replies only).
forwarded	boolean	true when the message was forwarded.
participant	string	Context participant JID, e.g. the author of a quoted group message.
fromMe	boolean	false for received messages, true for sent ones.

Example POST body

json

{
  "id": "9b2f6c1e-4d7a-4e8b-a1f3-5c0d2e7b8a64",
  "event": "messages.send",
  "sessionId": 1,
  "data": {
    "userId": 42,
    "sessionId": 1,
    "phoneNumber": "447476686841",
    "messageId": "3EB0ABCD1234EF567891",
    "internalId": 98232,
    "from": "447476686841@s.whatsapp.net",
    "to": "12025550147@s.whatsapp.net",
    "fromNumber": "447476686841",
    "toNumber": "12025550147",
    "chatId": "12025550147@s.whatsapp.net",
    "chatNumber": "12025550147",
    "content": "Check out this image",
    "type": "image",
    "mediaUrl": "https://cdn.chatpingo.com/media/1/3EB0ABCD1234EF567891.jpg",
    "mediaFileName": "product.jpg",
    "mediaFileType": "image/jpeg",
    "mediaFileSize": 84213,
    "isGroup": false,
    "isBroadcast": false,
    "isChannel": false,
    "timestamp": "2026-10-12T09:42:15.000Z",
    "timestampUnix": 1791798135,
    "fromMe": true
  },
  "timestamp": "2026-10-12T09:42:15.512Z"
}

EVENTsession.qr

QR code updated

A new QR code is ready to scan while the session is linking. WhatsApp rotates it every ~20 seconds, so you may get several in a row.

data fields

Field	Type	Description
userId	number	Your ChatPingo account id.
sessionId	number	The session being linked.
qr	string	Raw QR string. Render it as a QR code for the user to scan in WhatsApp → Linked devices.
qrFirstSeenAt	string	When the first QR of this linking attempt was issued, ISO 8601.

Example POST body

json

{
  "id": "9b2f6c1e-4d7a-4e8b-a1f3-5c0d2e7b8a64",
  "event": "session.qr",
  "sessionId": 1,
  "data": {
    "userId": 42,
    "sessionId": 1,
    "qr": "2@Xk3vQy9bZ...,4Fq1u7...,Jb9N2c...,Wm0lYQ==",
    "qrFirstSeenAt": "2026-10-12T09:30:00.000Z"
  },
  "timestamp": "2026-10-12T09:42:15.512Z"
}

EVENTsession.pairingCode

Pairing code issued

A pairing code was generated for linking by phone number instead of QR. Enter it in WhatsApp → Linked devices → Link with phone number.

data fields

Field	Type	Description
userId	number	Your ChatPingo account id.
sessionId	number	The session being linked.
pairingCode	string	8-character pairing code.
qrFirstSeenAt	string	When this linking attempt started, ISO 8601.

Example POST body

json

{
  "id": "9b2f6c1e-4d7a-4e8b-a1f3-5c0d2e7b8a64",
  "event": "session.pairingCode",
  "sessionId": 1,
  "data": {
    "userId": 42,
    "sessionId": 1,
    "pairingCode": "K7QM2XPA",
    "qrFirstSeenAt": "2026-10-12T09:30:00.000Z"
  },
  "timestamp": "2026-10-12T09:42:15.512Z"
}

EVENTsession.connected

Session connected

The number is linked and online, after scanning the QR or after reconnecting.

data fields

Field	Type	Description
userId	number	Your ChatPingo account id.
sessionId	number	The session that connected.
phoneNumber	string	WhatsApp JID of the linked device, e.g. 447476686841:12@s.whatsapp.net. The digits before ":" are the phone number.

Example POST body

json

{
  "id": "9b2f6c1e-4d7a-4e8b-a1f3-5c0d2e7b8a64",
  "event": "session.connected",
  "sessionId": 1,
  "data": {
    "userId": 42,
    "sessionId": 1,
    "phoneNumber": "447476686841:12@s.whatsapp.net"
  },
  "timestamp": "2026-10-12T09:42:15.512Z"
}

EVENTsession.disconnected

Session disconnected

The session went offline for good and needs a new QR scan. Short reconnects are not reported. Duplicate closes within 5 seconds are merged into one event.

data fields

Field	Type	Description
userId	number	Your ChatPingo account id.
sessionId	number	The session that disconnected.
reason	string \| null	logged_out (unlinked from the phone), manual (disconnected from ChatPingo), deleted (session deleted), replaced (re-linked to a new number), qr_timeout (QR not scanned in time), qr_exhausted (too many QR codes without a scan), bad_session (session data invalid), proxy_error (the session proxy stopped working; the session is paused).

Example POST body

json

{
  "id": "9b2f6c1e-4d7a-4e8b-a1f3-5c0d2e7b8a64",
  "event": "session.disconnected",
  "sessionId": 1,
  "data": {
    "userId": 42,
    "sessionId": 1,
    "reason": "logged_out"
  },
  "timestamp": "2026-10-12T09:42:15.512Z"
}

EVENTsession.failed

Session failed

ChatPingo gave up reconnecting the session automatically. Reconnect it from the dashboard.

data fields

Field	Type	Description
userId	number	Your ChatPingo account id.
sessionId	number	The session that failed.
reason	string	reconnect_exhausted (all retries failed) or no_capacity (no server could take the session).

Example POST body

json

{
  "id": "9b2f6c1e-4d7a-4e8b-a1f3-5c0d2e7b8a64",
  "event": "session.failed",
  "sessionId": 1,
  "data": {
    "userId": 42,
    "sessionId": 1,
    "reason": "reconnect_exhausted"
  },
  "timestamp": "2026-10-12T09:42:15.512Z"
}

EVENTsession.proxy_status

Proxy status changed

The health of the session's proxy changed. Opt-in: only delivered to webhooks that list this event explicitly, never to "all events" webhooks.

data fields

Field	Type	Description
userId	number	Your ChatPingo account id.
sessionId	number	The session whose proxy changed.
status	string	untested, healthy, degraded, failing or removed.
reason	string	proxy_added, proxy_changed, proxy_removed, retested, paused (proxy failed, session paused), fallback_server_ip (proxy failed, session now uses the server IP) or number_mismatch (the linked number differs from the expected one).
detectedIp	string \| null	Public IP seen through the proxy, or null when there is no working proxy.
detectedCountry	string \| null	Country code of detectedIp, e.g. AE.
expectedPhone	string	The number you expected to link (number_mismatch only).
linkedPhone	string	The number actually linked, e.g. +971501234567 (number_mismatch only).

Example POST body

json

{
  "id": "9b2f6c1e-4d7a-4e8b-a1f3-5c0d2e7b8a64",
  "event": "session.proxy_status",
  "sessionId": 1,
  "data": {
    "userId": 42,
    "sessionId": 1,
    "status": "healthy",
    "reason": "proxy_added",
    "detectedIp": "185.23.44.10",
    "detectedCountry": "AE"
  },
  "timestamp": "2026-10-12T09:42:15.512Z"
}