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 them both:


    • 192.117.146.95
    • 34.165.99.212 (new!)
    • 91.228.126.255 (no longer in use)
    • 5.47.173.231 (no longer in use)
    • 185.47.173.55 (no longer in use)


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


    • 192.117.146.95
    • 130.211.28.127 (New!)


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",
"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

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: nothing, empty

list: the item list that was selected

reaction: nothing, empty

order: the storeID

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)






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",
"to": "972501234567",
"ack": 1
}




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

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.

isNewConversation

This value is deprecated and will return 0.

see the new "isBilledTemplate" instead.

newConversationType

This value is deprecated and will return 0.

see the new "newTemplateType" instead.

isBilledTemplate

This value shows if a new billed template was sent to the client. This value will be sent only for 2 (delivered) or 3 (read) ack, but not on both. 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

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

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,1000,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.

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.

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

Created with the Personal Edition of HelpNDoc: Free Kindle producer