# 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, identified by the hook field:
"hook": "update"— Acknowledgment for Sent Messages:
For every message you send (text, file, location, or PTT), you can receive an acknowledgment when the message is sent, delivered, or seen by the recipient (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.
"hook": "system"— System Messages:
System messages allow you to receive a webhook when there is a new update about your account.The types of system messages you can get are:
- 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).
# acknowledge push example
json
Copy code
# Failed messages push example
json
Copy code
# Response parameters
| Name | Type | Description | Options |
|---|---|---|---|
| status | string | Always returns "OK". | |
| hook | string | The type of hook. | "update" for acknowledgment updates. "system" for failed messages. |
| type | string | Relevant only for "system" hooks. System message type. | "update" for daily limit updates."issues" for account issues."template" for templates update."messages" for messages update (failed messages). |
| unique | string | The same unique ID as the original message. | |
| to | string | Your WhatsApp account. | |
| from | string | Relevant only for the "update" hook - The WhatsApp number you tried to send the message to. | |
| messageTo | string | Relevant only for the "system" hook - The WhatsApp number you tried to send the message to. | |
| timestamp | timestamp | Relevant only for the "update" hook - The timestamp of the acknowledgment. | |
| 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. |
| isBilledTemplate | number | Indicates if a new billed template was sent to the client. Sent only for ack: 1 (sent), and only once per new billed template. A billed template is: any marketing template you send; any utility template you send if no incoming 24-hour session is open with the client; any authentication template you send. | 1 - new billed template.0 - no new billing event. |
| newTemplateType | number | When isBilledTemplate is 1, indicates the type of the new billed template. | 0 - no billing template.1 - utility template.2 - marketing template.3 - authentication template. |
| update | number | Relevant for "update" type only. Shows the new daily conversation limit for the WhatsApp account. | |
| issues | number | Relevant for "issues" type only. Shows account issue codes. | 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 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 | string | Relevant for "template" type only. The template name. | |
| templateUpdate | number | Relevant for "template" type only. Shows the status code for the relevant template. | 1 - Template approved and available to use.2 - Template rejected. Reason: wrong format / too many variables / template is similar to another template already in your account.3 - Template rejected. Reason: content violates WhatsApp policy.4 - Template rejected. Reason: content marked as spam.5 - Template rejected. Reason unknown.6 - Template received too many spam reports. You can't use this template for the next 6 hours.7 - Template is banned due to too many spam reports.8 - Template category has been changed.9 - The template has been deleted.10 - Template is flagged, it received a high amount of negative reports from users. Be careful!11 - Template is no longer flagged. |
| templateCategory | number | Relevant for "template" type only. Returned only when templateUpdate is 1 or 8. Shows the category this template is set to. | 1 - utility.2 - marketing.3 - authentication. |
# 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. |
| 14 | Marketing template limit reached: 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 | Template not found: The template you tried to send does not exist. |
| 16 | Rate limit exceeded: You are trying to send too many messages in a short period of time. Slow down. |
| 17 | Permission issue: Please contact support. |
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
json
Copy code
# 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) | |
| isNewConversation | number | Whether this message started a new incoming message conversation session or not.0 - this new message does not open a new conversation.1 - this new message opens a new conversation. | |
| order | array | This is a list of products order summary that was sent from your WhatsApp store. |