Webhook

Webhook allows you to get callback push API to your server, whenever there is an incoming message or status.

  • You need to set the Webhook URL within the Set Webhook API

  • Note! webhook messages might come from the following 2 IP addresses, in case you are required to whitelist, please whitelist this: 34.165.99.212

    If you wish to whitelist the IP of the API endpoints too (https://api.99digital.co.il/whatsapp/v2/) you should whitelist this IP: 130.211.28.127

Settings:

URL

Your URL

Method

JSON via POST


Incoming messages

With every incoming message, you will receive the following webhook:

{
"status": "OK",
"hook": "new",
"unique": "92E004B950CCEA3C386FCFA2AAF8558A",
"from": "972507654321",
"from_id": "IL.1605856887361213",
"username": null
"country": "IL",
"phone": "972507654321",
"to": "972501234567",
"senderName": "Ronen",
"type": "text",
"body": "hello",
"caption": "caption",
"isForwarded": false,
"timestamp": "1600517209",
"media": false,
"quote": false,
"quoteUnique": false,
"profilePic": "https://api.99digital.co.il/whatsapp/myfile/972501234567/file.jpg",
"conversationTimeLeft": "600"
}


Response-Explain:

Parameter

Description / Example

status

"OK" always

hook

"new" always. for new incoming message.

unique

Unique ID for the incoming message

from

The contact person that sent you the message, in international format: 972507654321

If the person is hiding his identity (enabled the 'username' feature) this value will return the from_id. for example: IL.1605856887361213

from_id

This is the contact person (sender) user id. this will always return back even if the client did not hide his identity. the format is always 2 digits country code + dot + 16 digits

this value is fixed per end user per WhatsApp api account. example: IL.1605856887361213

you can use this value to send messages to client.

username

The client username he chose for his WhatsApp. this feature is not available yet and will return null until officially released by Meta.

country

The country code of the contact person (sender)

phone

The contact person phone number, in international format for example: 972507654321.

If phone number is not available (client hide his identity) this will return null

to

Your WhatsApp account.

senderName

The name of the person that sent the message.

type

Message type. can be one of the following: text, image ,audio, video, location, ptt, document, button, contacts, list, reaction, order

body

The content of the 'body' depends on the 'type' of the message:

text: incoming text message

image: link

audio: link

video: link

location: lat,lng

ptt: link

document: link

button: button text

contacts: phone number

list: the selection text

reaction: the emoji

order: array of order items of the store

** you must download the link files to your server. we delete all files within 7 days.

caption

The content of the 'caption' depends on the 'type' of the message:

text: nothing, empty.

image: caption text with the image

video: caption text with the video

location: caption text with the location

ptt: caption text with the ptt

contacts: name of the contact

button: the ID of the button that was selected (this ID is arriving for 'sendButtons' and 'sendCarousel' button ID)

list: the item list ID that was selected

reaction: nothing, empty

order: the store ID number

isForwarded

Shows if the incoming message is forwarded. true or false

timestamp

Time stamp of the incoming message.

timestampMS

The millisecond part of the timestamp, in case you need it

media

If this message contains any media file, it will be true. otherwise - false

quote

If this message is a quoted message, if will be true. otherwise - false

quoteUnique

in case the message is quoted (it means that someone reply to your outgoing message), this will be the original message unique ID. if message is not quoted, this will be 'false'.

profilePic

jpg file link to the client's profile picture, if the user has a profile picture and his privacy settings allows it.

** Profile picture links are generated once per number.

conversationTimeLeft

amount of minutes left for the incoming conversation session to end. if passed, any incoming message after that, will be considered as a new incoming conversation, and the timer will reset.

isNewConversation

Whether this message started a new incoming message conversation session or not.

0 - this new message does not open new conversation.

1 - this new message opens a new conversation

referral

Object of items that describes the original referral that initiated the incoming WhatsApp message.

available data:

ref_type: 'none' (for none referral incoming message), 'post' (facebook/instagram post) or 'ad' (facebook/instagram campaign).

if the ref_type is 'post' or 'ad', more information will be available:

ref_title: the title of the post/ad

ref_body: the message of the post/ad

ref_id: id of the post/ad

ref_link: link to the post/ad

ref_image: image of the original post/ad (link will be deleted in 7 days)

order

This is list of products order summary that was sent from your WhatsApp store.

this parameter is array of items, looks like this:

[
    {
      "product_retailer_id": "woo_92",
      "quantity": 2,
      "item_price": 24,
      "currency": "ILS"
    },
    {
      "product_retailer_id": "woo_70",
      "quantity": 3,
      "item_price": 10,
      "currency": "ILS"
    },
    {
      "product_retailer_id": "woo_62",
      "quantity": 1,
      "item_price": 200,
      "currency": "ILS"
    }
  ]

explain:

product_retailer_id: the product id for the item

quantity: the quantity of that product

item_price: the price for each product

currency: the curreny of that product


Acknowledge

For every message or template you send, you can get acknowledge if the recipient saw your message or not.

There are three available statuses: sent, delivered, read.


Settings:

URL

Your URL

Method

JSON via POST


With every acknowledge message, you will receive the following:

{
"status": "OK",
"hook": "update",
"unique": "92E004B950CCEA3C386FCFA2AAF8558A",
"from": "972507654321",
"from_id": "IL.1605856887361213",
"country": "IL",
"phone": "972507654321",
"to": "972501234567",
"timestamp": "1779969217"
"conversationTimeLeft": 1143,
"isBilledTemplate" 0,
"newTemplateType": 0,
"isNewConversation": 0,
"newConversationType": 0,
"ack": 3
}


Response-Explain:

Parameter

Description / Example

status

"OK" always

hook

"update" always. for acknowledge update message.

unique

The same unique ID as the original message. this parameter allows you to know which message was seen.

to

Your WhatsApp account.

from

The contact that you sent the message to.

if you messaged to a normal international number, this will return the number.

if you messages to a user id (2 digits country code + dot + 16 digits) this will return this value.

from_id

The user id of the contact that you sent the message to

country

The country code (two digits) of the contact that you sent message to

timestamp

the timestamp of the ack

conversationTimeLeft

The time (in minutes) that is left for the conversation between you and the end user to finish in case an incoming conversation is open between you and the client. a conversation is a 24 hours session.

isBilledTemplate

This value shows if a new billed template was sent to the client. This value will be sent only for 1 (sent).

You will get this only once per new billed template.

if this value is 1, it means new template is billed.

if this value is 0 it means no new billing event.

A billed template is:

  • any marketing template you send.

  • any utility template you send if no incoming 24 hours session is open with the client.

  • any authentication template you send.

newTemplateType

In case new billed template is created under isBilledTemplate, here you can know the type of the template:

value

explanation

0

no billing template

1

utility template

2

marketing template

3

authentication template

ack

acknowledge type

0

Message failed to deliver. for more information, check the 'System Messages' section below

1

acknowledge that the message was sent (one gray check mark)

2

acknowledge that the recipient received the message (two gray check mark)

Message marked as delivered.

3

acknowledge that the recipient read the message (two blue check mark)

Message marked as read.

this ack only available if the recipient allowed it within his WhatsApp privacy settings inside the mobile app.


Important note: The word "conversation" can be a little confusing regarding how it is counted and billed. please see this page for more information: Template, conversation and Message


System Messages

System messages allows you to receive webhook when there is a new update about your account.

The type of system messages you can get is:

  • Daily limit of outgoing conversations (250,2000,10000 etc).

  • Cases where your WhatsApp number is flagged due to spam reports.

  • Message template approved or rejected.

  • Message template ongoing spam reports.

  • Failed messages (messages that you tried to send but they failed).

  • Account blocked (due to spam or any other reason).

System messages are turned off by default. you can enable this in the "Set Webhook" endpoint.

Settings:

URL

Your URL

Method

JSON via POST


With every system message, you will get some of the following response:


{
"status": "OK",
"hook": "system",
"type": "update / issues / template / messages",
"to": "972541111111",
"timestamp": 1740049366
"update": 1000,
"issue": 1,
"template": "welcome_message",
"templateUpdate": 1,
"unique": "92E004B950CCEA3C386FCFA2AAF8558A",
"messageUpdate": 5,
"messageTo": "972501234567"
}


Response-Explain:

Parameter

Description / Example

status

"OK" always

hook

"system" always. for system update message.

type

System message type.

values:

for daily limit updates: "update"

for account issues: "issues"

for templates update: "template"

for messages update: "messages"

to

Your WhatsApp account.

timestamp

The timestamp of the information

update

relevant for "update" type only.

will show the new daily conversation limit for the WhatsApp account.

issues

relevant for "issues" type only.

Here you can get account issues. if there are some account issue, one of the following codes will be returned:

code

explanation

1

Your account is flagged due to spam. be careful!

2

Your account is no longer flagged.

3

Your account has been blocked from WhatsApp.

4

Your account is back to be active again after being blocked/reviewed

5

The phone number has been removed from the business manager, please contact support

6

The account has been deleted, please contact support

7

Access to the account has been removed by the client. please contact support

8

Your account was sent to review by Meta

template

relevant for "template" type only.

will show the template name.

templateUpdate

relevant for "template" type only.

will show the status code for the relevant template:

code

explanation

1

Your template has been approved and available to use.

2

Template rejected. reason: wrong format template / too many variables / template is similar to other template already exist in your account.

3

Template rejected. reason: The template contains content that is violating WhatsApp policy.

4

Template rejected. reason: The template contains content that is marked as Spam.

5

Template rejected. reason unknown.

6

Template received too many spam reports. you cant use this template for the next 6 hours.

7

Template is banned to use due to too many spam reports.

8

Template category has been changed.

9

The template has been deleted.

10

The template is flagged, it received high amount of negative reports from users. be careful!

11

The template is no longer flagged

templateCategory

relevant for "template" type only, and will only come when templateUpdate = 1 or 8

will show the category that this template is set to

1 - utility

2 - marketing

3 - authentication

unique

relevant for "messages" type only.

this is the unique ID of the message that was sent

messageUpdate

relevant for "messages" type only.

will show the status code for messages that failed to deliver:

code

explanation

1

Server error, try to send the message again.

2

Billing issue, please contact support to fix the billing.

3

Attached file is incorrect, please try to re-send the message and fix the file.

4

Account is blocked for sending messages

5

You have reached your daily limit for sending messages

6

The 'to' and 'from' parameters are the same. you can't send a message to yourself.

7

The WhatsApp number you tried to send the message to is using an old WhatsApp app, or did not accept WhatsApp 'terms of use' within his app.

8

Its been more than 24 hours since the client's last reply, please use Template instead.

9

Error unknown, please contact support.

10

Variables error, please check the variables used in the template (either body variable or header link)

11

Context issue in the body or header of the message

12

The template you tried to send was not approved to use by Meta

13

The client can't receive this template message now because his number marked as "trial". contact support for more information.

14

You can't send more than two marketing templates to the same number within 24 hours. please wait for the user to reply first.

15

The template you tried to send does not exist.

16

You are trying to send too many message in a short period of time. slow down.

17

Permission issue. please contact support

messageTo

Relevant for "messages" type only.

The WhatsApp number you tried to send the message to


Contacts update

Contacts update allows you to receive webhook when there is a new update about your WhatsApp contacts. a contact is end user WhatsApp number that you are chatting with.

The type of system messages you can get is:

  • For coexistence accounts, when a contact is added or changed.

  • For coexistence accounts, when a contact is deleted.

  • When a contact asked to stop receiving marketing messages. (future update, not on production now).

  • When a contact asked to keep receiving marketing messages. (future update, not on production now).

  • When a contact accepted your WhatsApp API to call him using WhatsApp Calls. (future update, not on production now).

Contacts update are turned on by default.


Settings:

URL

Your URL

Method

JSON via POST


With every system message, you will get some of the following response:


{
"status": "OK",
"hook": "outgoing",
"unique": "92E004B950CCEA3C386FCFA2AAF8558A",
"from": "972501234567",
"to": "972507654321",
"type": "text",
"body": "hello",
"caption": "caption",
"isForwarded": false,
"timestamp": "1600517209",
"media": false,
"quote": false,
"quoteUnique": false
}

Response-Explain:

Parameter

Description / Example

status

"OK" always

hook

"contact" always. for contact webhooks

type

Contact webhook type.

values:

for coexistence contact update: "coexistence"

for marketing requests: "marketing"

for calls requests: "calls"

to

Your WhatsApp account.

contact

The end user WhatsApp number

timestamp

The timestamp of the information

coexistence

Relevant for "coexistence" type only.

This will show "add" if new contact was saved to the whatsapp business app phone contact list

This will show "remove" if the whatsapp business app removed a phone from the contact list

marketing

Relevant for "marketing" type only.

This will show "remove" if a contact asked to stop getting marketing messages.

This will show "add" if the contact asked to resume getting marketing messages.

(this is a future feature)

calls

Relevant for "calls" type only.

This will show "add" if a contact allows your business to call him over WhatsApp

This will show "remove" if the contact is no longer allowing your business to call him over WhatsApp

(this is a future feature)

contact_name

Relevant for "coexistence" type only and "add" coexistence

This will show the contact_name of how it was saved in the whatsapp business app in the mobile phone


Outgoing messages

Outgoing messages webhooks are only relevant to "coexistence" whatsapp accounts. it will show outgoing messages send by the user himself from his mobile phone whatsapp business app (or whatsapp web) outside of the API.

This is only relevant to let you know the user sent a message in case you want to show this as outgoing message in your platform.

Note: any outgoing message sent from the API will not trigger outgoing message webhook.

Outgoing messages webhooks are turned on by default.

Note 2: outging messages to groups is not supported.


Settings:

URL

Your URL

Method

JSON via POST


With every system message, you will get some of the following response:

{
"status": "OK",
"hook": "outgoing",
"unique": "92E004B950CCEA3C386FCFA2AAF8558A",
"from": "972501234567",
"to": "972507654321",
"type": "text",
"body": "hello",
"caption": "caption",
"isForwarded": false,
"timestamp": "1600517209",
"media": false,
"quote": false,
"quoteUnique": false
}


Response-Explain:

Parameter

Description / Example

status

"OK" always

hook

"outgoing" always. for new outgoing message.

unique

Unique ID for the outgoing message

from

Your WhatsApp account

to

The end user WhatsApp account that received the message

type

Message type. can be one of the following: text, image ,audio, video, location, ptt, document, button, contacts, list, reaction

body

The content of the 'body' depends on the 'type' of the message:

text: outgoing text message

image: link

audio: link

video: link

location: lat,lng

ptt: link

document: link

button: button text

contacts: phone number

list: the selection text

reaction: the emoji

** you must download the link files to your server. we delete all files within 7 days.

caption

The content of the 'caption' depends on the 'type' of the message:

text: nothing, empty.

image: caption text with the image

video: caption text with the video

location: caption text with the location

ptt: caption text with the ptt

contacts: name of the contact

button: nothing, empty

list: the item list that was selected

reaction: nothing, empty

isForwarded

Shows if the outgoing message is forwarded. true or false

timestamp

Time stamp of the outgoing message.

timestampMS

The millisecond part of the timestamp, in case you need it

media

If this message contains any media file, it will be true. otherwise - false

quote

If this message is a quoted message, if will be true. otherwise - false

quoteUnique

in case the message is quoted (it means that the client relpied to an incoming message), this will be the original message unique ID. if message is not quoted, this will be 'false'.