Create a new webhook subscription

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.

Event	Description
whatsapp.call.received	Triggers when a new WhatsApp call is received and missed
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
whatsapp.order.received	Triggers when a new WhatsApp order is received
whatsapp.message.sent	Triggers when a new WhatsApp message is sent
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 group related events:

Event	Description
whatsapp.group.message.received	Triggers when a message is received on a WhatsApp group your number is part of
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:

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

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.

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

info

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

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)

NodeJS

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 a 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