NAV
Curl

Tujenge WhatsApp API Version 1

This documentation explains how to get access to direct-like WhatsApp for Business API.

The WhatsApp API supports all endpoints from WhatsApp docs, except for the ones blacklisted below. Additionally we enable you to set your base path.

Blacklisted paths:

Settings (v1/settings/*) except allowed: /v1/settings/business/profile, /v1/settings/profile/about,/v1/settings/profile/photo.)

Certificates (/v1/certificates/*)

Registration (/v1/account)

Health check (/v1/health)

Stats and metrics (/v1/stats/*|/metrics)

Support (/v1/support)

Users (/v1/users/*)

Authorization

This documentation describes how you get access to the WhatsApp API.

Every request to WhatsApp API needs to be authorized using API Key authentication. Adding WA-API-KEY header with your api key as a value is enough to gain permission.

Every API Key is connected with exactly one phone number. We authenticate and choose the right project by your API Key. So, if you want to switch between the projects you need to authorize your requests with other API Key.

Example

$ curl -H 'WA-API-KEY: <<api-key>>' https://waba.tujenge.io/v1/stickerpacks

$ curl -H 'WA-API-KEY: <>' https://waba.tujenge.io/v1/stickerpacks

How can I get the API-KEY?

Send a request for your API KEY to [email protected]

If you do not include the token or do not follow the correct format, your request will fail.

Also make sure to:

safely store and manage your API-key and use it only for server-2-server authentication.

ensure that you always use the corresponding API-key when you deal with multiple configurations. A mismatch could lead to inconsistent data!

Webhook

This documentation describes how to setup Webhooks.

Introduction

Use the Webhook to determine to which endpoint we should forward the Notifications.

Optional: headers may be used to add authorization of webhook calls.

API Reference

Authorization information can be found in Authorization

Set Webhook URL

POST /v1/configs/webhook

WA-API-KEY: API-Key

Content-Type : application/json

      {
        "url": URL,
        "headers": {
          "header_1": string,
          "header_2": string
        }
      }

Response 200

      {
        "url": "https://www.example.com/webhook",
        "headers": {
          "Authorization": "Basic dGVzdHVzZXI6dGVzdHBhc3M="
        }
      }

Response 40X

        {
          "meta": {
            "success": false | true,
            "http_code": 40X,
            "developer_message": string,
            "details": [
              string
            ]
          }
        }

Response 50X

          {
            "meta": {
              "success": false,
              "http_code": 500,
              "developer_message": string
            }
          }

Messaging

This documentation describes how to start sending messages to your users.

Introduction

Message API calls are sent to the /messages endpoint regardless of message type, but the content of the JSON message body differs for each type of message (text, image, etc.). See the following documentation for information regarding the type of messages you want to send:

Text Messages

Media Messages

Message Templates

Group Messages

Other Message Types

Message Templates

Message templates need approval from the WhatsApp team and are set up and configured by the customer success team ([email protected]).

  1. Each WhatsApp Business Account can have up to 250 message templates (how many is determined by your plan). That means 250 message template names, each of them can have multiple language translations. For example, a message template called hello_world translated into two languages counts as a singe message template in regards to this limit.
  2. The message template name field is limited to 512 characters.
  3. The message template content field is limited to 1024 characters.
  4. There is no limit to the number of parameters allowed in a Message Templates.

Messages Error scenarios

  1. '400','Bad Request'

Check that you are using the correct data type for Booleans and Strings, and that the JSON-payload is well-formed. Use an online tool (ex. JSON formatter and validator) to validate the payload if you are not sure.

  1. '408', 'Message failed to send because it was pending for too long'

There are no further details provided by WhatsApp. The recommendation is to resend the message.

  1. '470','Message failed to send because more than 24 hours have passed since the customer last replied to this number' Free-form text messages and media messages will result in a failure callback with error 470 when sent outside of the 24h-window. Please find a way to restrict message sending if there was no incoming message for the given user/phone number within 24h.

  2. '1000', 'Failed to generate processed file path' This could occur when the file storage is full and files cannot be stored. Please reach out to [email protected]

  3. '1000', 'Image file format (audio/mpeg) is not supported' Make sure that the message type matches the MIME-type of the file (ex. audio files should be sent using "audio", not "image"; audio/mpeg is an unsupported combination). Another reason could be that the video file doesn't have an audio track: then the error message contains something like video/mp4/h264/NONE where NONE is an indicator that the audio track is missing.

  4. '1009', 'Invalid latitude'

Valid range is from -90 to 90.

  1. '1014','Request for .... failed'

You have provided a URL which seems to be double URL-encoded and the file cannot be delivered because of that, or the file behind the URL doesn't exist.

  1. '2001','Template name does not exist in the translation'

The template needs to be set up by customer success management ([email protected]).

  1. '500','structure unavailable: Client could not display highly structured message'

Template was not understood by the WhatsApp consumer client. Check the format.

Notifications

This documentation describes how to receive Webhook Callback Events in your system.

Introduction

When a customer sends you a message, the WhatsApp Business API client will send an HTTP POST request notification to the Webhook URL with the details that are described in the following documents:

Inbound Message Notifications

Inbound Media Message Notifications

Inbound Replies to Sent Messages

Inbound System Messagess

Outbound Message Status Notifications

Webhook Error scenarios

302-redirect: Redirects are not followed by the Webhook gateway

Please ensure that there is always HTTP 200 as a response code.

SSL-errors: Please ensure that the Callback-URLs are using SSL/TLS and that the certificates are valid and that the certificate chain is complete.

You start processing in the callback thread. Please do only acknowledge messages and notifications and start processing in a separate thread.

Callbacks will be terminated after a defined timeout and there will be a retry.

Duplicates messages can be sent to a WhatsApp Webhook as the only guarantee provided is that messages will be received at least once (as opposed to exactly once). If this is affecting how messages are processed on your end, then we suggest dedup-ing Webhook messages based on the message_id.

Please reach out via Customer Success Management ([email protected]) if you need to understand the current settings.

Best Practices

Successfully send and receive messages

Journey into WhatsApp

Consent Flows

Consent flows support both brand- and user-initiated conversations. Customer success management ([email protected]) can share know-how how you can create widgets and descriptions for Desktop Web, Mobile Web, e-mail, print to drive users into the messenger, ensuring that the opt-in gets captured and stored.

The MT-Flow (MT=mobile-terminated) is intended for Desktop users where it's not clear if they have installed the app. Users check the box and enter their phone number. In eCommerce solutions the phone number might be already available - it can be pre-populated. The consent management would then send a welcome message (aka Welcome MT) to the given phone number.

The MO-Flow (mobile-originated) is intended for users who reach out on their own, by following a link to WhatsApp Web, by scanning a QR-code, or by typing in or sharing the phone number. In the user-initiated chat session, the consent management will first ask the user to agree on the terms & conditions. If the user agrees, the conversation can continue, if the user disagrees, then his profile and the incoming message get deleted.

Always ask for an active opt-in from the user. Any communication from the WhatsApp endpoint requires an active opt-in. "Active" means that it must be triggered by a user action, such as entering a phone number or checking a box to indicate consent (please consult the Opt-In requirements).

WhatsApp has a reporting and blocking mechanism that gets activated when the user receives a message without reaching out before (in a notifications case). If the user is unaware of receiving notifications this might lead to an increase in blocked numbers or users that want to opt-out. Try to get the Official Business Approval to show your brand instead of the WhatsApp number.

WhatsApp allows users to report spam or to even block the number - a quality signal

Try to get started with MO-flows and send your business contact, so the customer can store it on his/her phone. This will improve the user experience and will reduce the risk of being flagged.

Send contact card early in the process

Deep & Universal Links

https://wa.me/?text= will take the user straight into WhatsApp (if it's installed) or to a landing page hosted by WhatsApp (if it's not installed).

Deeplinks

whatsapp://r - account confirmation link - which doesn' seems to not work on iOS

whatsapp://send - contact picker

whatsapp://chat - HomeActivity

upi://pay - payments

Universal Links

http[s]://v.whatsapp.com - verify SMS deeplink

http[s]://api.whatsapp.com- text and direct chat deeplink

http[s]://wa.me- text and direct chat deeplink

http[s]://chat.whatsapp.com - accept invite link deeplink

Contact validation

Ensure that you only pass phone numbers consisting of digits, no leading zeros and a country prefix - use an E.164-format validation .

Use a phone number validation library such as Google's phonelib or a number database such as Numverify, RealPhoneValidation or others to validate that the given number is well-formatted and that it should be valid; consider exceptions for Mexico and Argentina.

Check the contact-endpoint before sending messages

Check the contact-endpoint before sending messages

Message sending

Manage cut-off control (don't send other messages than templated-based messages if there is a 470 response).

Don't go crazy and send text messages with more than 4096 characters.

If you intend to benefit from URL-unfurling and you set preview_url to true the text message must contain a valid URL.

Make sure that the file type is supported by WhatsApp and that the file size doesn't exceed given limit: video files must have an audio track audio and video files will require codecs supported by WhatsApp.

Send files and images using a link rather than uploading them first.

a) Store & Forward - the media file needs to be uploaded to the WhatsApp gateway (Google Cloud Platform -> Partner's client (client's country).

b) Send-file-as-link - the media file is referenced in the message and served from the partner's server.

Add a wa_id to the phones-object when the user receiving a contact shall be able to save it to the phone.

        "phones": [
                                            {
                                                "phone": "+1 (940) 555-1234",
                                                "type": "HOME"
                                            },
                                            {
                                                "phone": "+1 (650) 555-1234",
                                                "type": "WORK",
                                                "wa_id": "16505551234"
                                            }
                                        ]

When you send a phone number without a wa_id it's only possible to "invite" users. If the wa_id (=E.164-formatted version of the phone number) is given the WhatsApp client will allow to "adding a contact" and "sending a message" which might come in different flavours on Android and iOS.

Implement the typical error scenarios mentioned in the FAQ.

Implement handling for the quality limit - "warm up" the number when sending template-based messages; there will be a capping when the quality limit has been reached and the number will be switched to "Restricted" by Facebook for 24h.

Make use of message formatting: bold (*), italics (_), ~strikethrough~ (~) and mono-space (```).

Latency issues

Respect that WhatsApp might have latencies in their network or that the user's device or app install might have issues which might impact message delivery. Possible reasons for delays seem to be device and/or network related which is not in our hands. See

Troubleshooting guide by WhatsApp

Reddit articles on delayed message delivery

How to speed up the WhatsApp client

Reasons for delayed, incoming messages

Outbound Message Status Notifications

Typical fixes include:

resetting the cache on the WhatsApp consumer app

resetting the network connection

killing and restarting the WhatsApp consumer app

ensuring that there is enough RAM available for the WhatsApp consumer app

saving the contact in the address book you are trying to reach

Callback handling

Only asynchronous handling of callbacks - acknowledge first, then process

Use valid SSL-certificates for the callback endpoint - the certificates must support TLS1.3, the certificate chain must not be broken.

Make sure that the DNS-entry of the callback endpoint is propagated and registered with official DNS-servers (ex. 8.8.8.8).

Chatbot integrations

Have standard response while the service is not fully active:

"Thank you very much for contacting us. Please note that this service is not yet fully operational. We plan to officially start on yyyy/mm/dd. Thank you for your patience."

Review that your chatbot does meet these minimum standards:-

Branding

Brand consistency: Does it look and feel like the company’s does it look out of place?

Conversational: Is the bot appropriately conversational? Does it use small talk, greets, engages?

Language consistency: Does the bot use language and phrasing that is consistent with the brand's website and image?

Performance

Purpose: Is it clear what this bot is meant to do? Can you tell what the One True Goal is?

Effectiveness: Is it effective at its job? Does it provide the right help?

Knowledge: Can it answer common questions around the task it was built to perform? Can it help the user?

Feedback: Does it let the user know they are progressing towards their goal?

Consistency

Doing its job: Can the bot consistently help the user achieve their goal?

Journey consistency: Does the path the bot takes users fit the expected path the company would take them on?

Up to date: Is the bot up to date?

Knowledge: Does the bot have a consistent amount of knowledge across the different topics it touches on?

Humanity

  1. Transparency: Does it pretend to be a human? Is it transparent and honest about being a machine?

  2. Self-aware: Can it answer questions about itself? Does it know and is open about its limitations?

  3. Reaching humans: Can it hand conversations over to its human colleagues gracefully? Does it inform the users on how to skip straight to a humans.