Subscribe to WhatsApp-related events

Posting a request to this endpoint will create a new webhook subscription to the specified event.

List of accepted events

Any of these events can be specified as a query parameter in the invocation URL.

info

Check out some of the payload examples.

💡 You can also subscribe and unsubscribe to events manually. Learn more here.

Event	Description
whatsapp.call.received	Triggers when a new WhatsApp call is received or missed on your connected number. Example.
whatsapp.call.made	Triggers when a new WhatsApp call is made using the WhatsApp application for your connected number. Example.
whatsapp.message.new	Triggers when a new WhatsApp message is either sent or received.
whatsapp.message.received	Triggers when a new WhatsApp message is received. Example.
whatsapp.order.received	Triggers when a new WhatsApp order is received. Example.
whatsapp.message.sent	Triggers when a new WhatsApp message is sent. Example.
whatsapp.conversation.new	Triggers when a new WhatsApp conversation is started.
whatsapp.audio.transcribed	Triggers when a new WhatsApp audio message is transcribed to text.
whatsapp.message.reaction	Triggers when someone reacts to a message. Example.
whatsapp.message.edited	Triggers when a message is edited. It will also trigger for group messages being edited. Example.

WhatsApp group related events:

info

If you want to capture these events only for a specific group, use the to_group_uuid parameter.

Event	Description
whatsapp.group.message.received	Triggers when a message is received on a WhatsApp group your number is part of.
whatsapp.group.message.reaction	Triggers when a group participant reacts to a message.
whatsapp.group.join	Triggers when someone joins a group.
whatsapp.group.leave	Triggers when someone leaves a group.
whatsapp.group.remove	Triggers when someone is kicked/removed from a group.

WhatsApp message receipt events:

info

it's important to consider that 2Chat can only see messages arriving after the time you connected your number to our service. Messages that arrived prior to this connection are not visible to us.

Event	Description
whatsapp.message.receipt.sent	Triggers when a message you sent is in the process of being delivered to the receiver.
whatsapp.message.receipt.received	Triggers when a message you sent is received on the app of its intended receiver.
whatsapp.message.receipt.read	Triggers when the receiver reads a message you sent, provided the receiver has read-receipts enabled. Example.

WhatsApp number status events:

Event	Description
whatsapp.number.status	Triggers when a WhatsApp number you connected to 2Chat changes status. E.g.: ready (connected), disconnected, qr-received, loading, etc. Example.

tip

In the case of qr-received event, you can also obtain the latest QR code value using the Get QR Code Endpoint.

Event types:

Type	Description
initializing	The container hosting your connection is starting.
qr-received	The number is disconnected and awaiting a new connection by scanning the generated QR code.
loading	The connection succeeded and it's loading.
ready	The connection finished loading and is ready to receive and send messages.
disconnected	The number has disconnected. Check potential reasons below.

caution

You may receive initialization and loading events several times during the lifecycle of your connection. This can happen because the container is restarted automatically or crashes. Unless you receive a disconnected event, your connection remains active.

Disconnection reasons:

Type	Description
No specified reason	Unknown disconnection reason.
qr_scan_timeout	The QR code was never scanned.
user_requested	The user deleted their number or disconnected manually using 2Chat.
logout	The user removed the connection or linked device from the WhatsApp application, or the connection expired and removed itself.
account_locked	The number was banned.
sync_failure	The number disconnected because it could not finish syncing.

Parameters

info

These parameters should be sent as JSON payload in the request body.

Field	Description
hook_url	A valid and publicly reachable URL that 2Chat will invoke when the event is triggered
on_number	The phone number that you have configured and connected to 2Chat. Always make sure it is connected
time_period	Required only if you are subscribing to whatsapp.conversation.new.

For the whatsapp.conversation.new event, you can specify also the time period of your preference to consider a conversation new.

Time Period Value	Description
all-time	Will trigger the new conversation event when the user messages you for the first time ever. This is the default value when no time period is specified
hour	Will trigger the new conversation event after 1 hour of no messages
day	Will trigger the new conversation event after 1 day of no messages
week	Will trigger the new conversation event after 1 week of no messages
month	Will trigger the new conversation event after 1 month of no messages
year	Will trigger the new conversation event after 1 year of no messages

Filtering events on WhatsApp groups

For any of the group-related events, such as whatsapp.group.message.reaction, you can restrict the triggering of events by passing an extra payload parameter that will make the webhook only be called when the event occurs on the configured group.

Field	Description
to_group_uuid	UUID of the group where the event should trigger to call your webhook. By default, its value is any and will trigger for the event happening on any of your WhatsApp groups.

Invocation

Assume we want to subscribe to the event whatsapp.message.received as example:

cURL

curl --location --request POST 'https://api.p.2chat.io/open/webhooks/subscribe/whatsapp.message.received' \
--header 'X-User-API-Key: your_api_key_here' \
--header 'Content-Type: application/json' \
--data-raw '{
    "hook_url": "https://www.toptal.com/developers/postbin/1681755466939-3421728690154",
    "on_number": "+595981048477"
}'

Python

import requests
import json

url = "https://api.p.2chat.io/open/webhooks/subscribe/whatsapp.message.sent"

payload = json.dumps({
  "hook_url": "https://www.toptal.com/developers/postbin/1681755466939-3421728690154",
  "on_number": "+595981048477"
})
headers = {
  'X-User-API-Key': 'your_api_key_here',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

JavaScript

var axios = require('axios');
var data = JSON.stringify({
  "hook_url": "https://www.toptal.com/developers/postbin/1681755466939-3421728690154",
  "on_number": "+595981048477"
});

var config = {
  method: 'post',
maxBodyLength: Infinity,
  url: 'https://api.p.2chat.io/open/webhooks/subscribe/whatsapp.message.sent',
  headers: { 
    'X-User-API-Key': 'your_api_key_here', 
    'Content-Type': 'application/json'
  },
  data : data
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

Response

The API will return the newly configured webhook if successful.

{
    "success": true,
    "data": {
        "uuid": "WHK530c9d58-2259-4ce2-82a8-1941f3a60665",
        "event_name": "whatsapp.message.sent",
        "channel_uuid": "WPN95841312-b54d-46e3-b0bc-6414f4a5296b",
        "hook_url": "https://www.toptal.com/developers/postbin/1681755466939-3421728690154",
        "hook_params": {
            "waweb_uuid": "WPN95841312-b54d-46e3-b0bc-6414f4a5296b"
        },
        "created_at": "2023-04-18T01:58:02Z"
    }
}

Field	Description	Example values
uuid	The unique identifier of the webhook that you will need to make changes to it	WHK530c9d58-2259-4ce2-82a8-1941f3a60665
event_name	The name of the event this webhook is subscribed to	whatsapp.message.sent
channel_uuid	The unique UUID of the channel this webhook is subscribed to	WPN95841312-b54d-46e3-b0bc-6414f4a5296b
hook_url	The URL 2Chat will call when a event is triggered	https://www.toptal.com/develop...
hook_params	Custom parameters 2Chat sets to make the webhook functional	{"waweb_uuid": "WPN95841312-b54d-46e3-b0bc-6414f4a5296b"}
created_at	UTC timestamp for when the webhook was created	2023-04-18T01:58:02Z