Whatsapp Push api

Note

all the whatsapp push api requests bodies send in application/json format.

Whatsapp Push DLR's

If you want to receive delivery reports pushed to your specific URL, you need to provide us with the URL through our web app. We will push DLR (Delivery Reports) upon arrival using an HTTP POST request.

The delivery report push can be of two types:

1. Acknowledgment for Sent Messages:
   For every message you send (text, file, location, or PTT), you can receive acknowledgment if the recipient has seen your message (indicated by the "seen" status with two blue check marks).

   Note: The acknowledgment for the two blue check marks only works if the recipient has enabled this option in their WhatsApp privacy settings.

2. Failed Messages:
   Notifications for messages you attempted to send but failed to deliver.

acknowledge push example

Content-Type: application/json

{
    "status": "OK",
    "hook": "update",
    "unique": "92E004B950CCEA3C386FCFA2AAF8558A",
    "from": "972552222222",
    "to": "972553333333",
    "ack": 1
}

Failed messages push example

Content-Type: application/json

{
    "status": "OK",
    "hook": "system",
    "type": "messages",
    "to": "972553333333",
    "timestamp": 1688370011,
    "unique": "HBgMOTcyNTI3MTY1MDM1FQIAERgSOUU1Q0VBNzVFRUUxRkVCRTM3AA==",
    "messageUpdate": 7,
    "messageTo": "972552222222"
}

Response parameters

Name	Type	Description	Options
status	string	Always returns "OK".	true/false
hook	string	The type of hook.	"update" for acknowledgment updates. "system" for failed messages.
type	string	Relevant only for "system" hooks.	"messages" for failed messages.
unique	string	The same unique ID as the original message.	N/A
to	string	Your WhatsApp account.	N/A
from	string	Relevant only for the "update" hook - The WhatsApp number you tried to send the message to.	N/A
messageTo	string	Relevant only for the "system" hook - The WhatsApp number you tried to send the message to.	N/A
timestamp	timestamp	Relevant only for the "update" hook - The timestamp of the acknowledgment.	N/A
ack	number	The acknowledgment type.	0 - Message failed to deliver (you will receive a failed message push with a specific error). 1 - Acknowledgment that the message was sent (one gray check mark). 2 - Acknowledgment that the recipient received the message (two gray check marks). 3 - Acknowledgment that the recipient saw the message (two blue check marks).
messageUpdate	number	Relevant for "messages" type only. Shows the status code for messages that failed to deliver.	See the table below.

Error Codes and Explanations of messageUpdate

Error Code	Explanation
1	Server error: Try to send the message again.
2	Billing issue: Please contact support to fix the billing.
3	Incorrect attached file: The attached file is incorrect. Please try to re-send the message and fix the file.
4	Account blocked: Your account is blocked for sending messages.
5	Daily limit reached: You have reached your daily limit for sending messages.
6	Invalid 'to' and 'from' parameters: The 'to' and 'from' parameters are the same. You can't send a message to yourself.
7	Outdated WhatsApp app: 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 the app.
8	24-hour limit exceeded: It's been more than 24 hours since the client's last reply. Please use a Template instead.
9	Unknown error: An unknown error occurred. Please contact support.
10	Variables error: There is an error with the variables used in the template. Please check the variables.
11	Context issue: There is an issue with the context in the body or header of the message.
12	Template not approved: The template you tried to send was not approved to use by Meta.
13	Client's number marked as "trial": The client can't receive this template message now because their number is marked as "trial". Contact support for more information.

Note

In case that the returned status code is not 200 OK we will hold the push to your URL for a while, After few failed attempts the PUSH will stop automatically.

Whatsapp Push incoming

In case you want to get incoming messages pushed to your specific URL ,you need to supply us with a URL in our webapp and we will push incoming on arrival using HTTP POST request.

incoming push example

Content-Type: application/json

{
    "status": "OK",
    "hook": "new",
    "unique": "92E004B950CCEA3C386FCFA2AAF8558A",
    "from": "972552222222",
    "to": "972553333333",
    "senderName": "Niv",
    "type": "text",
    "body": "hello",
    "caption": "caption",
    "isForwarded": false,
    "timestamp": "1600517209",
    "media": false,
    "quote": false,
    "quoteUnique": false,
    "conversationTimeLeft": "600"
}

Response parameters

Name	Type	Description	Options
status	string	"OK" always	true/false
hook	string	The hook type	"new" for new incoming message.
type	string	Message type. can be one of the following: text, image ,audio, video, location, ptt, document, button, contacts, list, reaction, order	"messages" for failed messages
unique	string	Unique ID for the incoming message
to	string	Your WhatsApp account.
from	string	The contact person that sent you the message, in international format: 972507654321
senderName	string	The name of the person that sent the message.
body	string	The content of the 'body' depends on the 'type' of the message	text: incoming text messageimage: 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	string	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	boolean	Shows if the incoming message is forwarded. true or false
timestamp	timestamp	Time stamp of the incoming message.
timestampMS	timestamp	The millisecond part of the timestamp, in case you need it
media	boolean	If this message contains any media file, it will be true. otherwise - false
quote	boolean	If this message is a quoted message, it will be true. otherwise - false
quoteUnique	string	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.
conversationTimeLeft	number	amount of minutes left for the conversation session to end. if passed, any message after that, will be considered as a new conversation, and the timer will reset.
referral	number	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)