Skip to main content

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.

EventDescription
whatsapp.call.receivedTriggers when a new WhatsApp call is received and missed
whatsapp.message.newTriggers when a new WhatsApp message is either sent or received
whatsapp.message.receivedTriggers when a new WhatsApp message is received
whatsapp.order.receivedTriggers when a new WhatsApp order is received
whatsapp.message.sentTriggers when a new WhatsApp message is sent
whatsapp.conversation.newTriggers when a new WhatsApp conversation is started
whatsapp.audio.transcribedTriggers when a new WhatsApp audio message is transcribed to text
EventDescription
whatsapp.group.message.receivedTriggers when a message is received on a WhatsApp group your number is part of
whatsapp.group.joinTriggers when someone joins a group
whatsapp.group.leaveTriggers when someone leaves a group
whatsapp.group.removeTriggers when someone is kicked/removed from a group

Parameters

info

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

FieldDescription
hook_urlA valid and publicly reachable URL that 2Chat will invoke when the event is triggered
on_numberThe phone number that you have configured and connected to 2Chat. Always make sure it is connected
time_periodRequired 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 ValueDescription
all-timeWill 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
hourWill trigger the new conversation event after 1 hour of no messages
dayWill trigger the new conversation event after 1 day of no messages
weekWill trigger the new conversation event after 1 week of no messages
monthWill trigger the new conversation event after 1 month of no messages
yearWill 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 --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"
}'

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"
}
}
FieldDescriptionExample values
uuidThe unique identifier of the webhook that you will need to make changes to itWHK530c9d58-2259-4ce2-82a8-1941f3a60665
event_nameThe name of the event this webhook is subscribed towhatsapp.message.sent
channel_uuidThe unique UUID of the channel this webhook is subscribed toWPN95841312-b54d-46e3-b0bc-6414f4a5296b
hook_urlThe URL 2Chat will call when a event is triggeredhttps://www.toptal.com/develop...
hook_paramsCustom parameters 2Chat sets to make the webhook functional{"waweb_uuid": "WPN95841312-b54d-46e3-b0bc-6414f4a5296b"}
created_atUTC timestamp for when the webhook was created2023-04-18T01:58:02Z