Whatsapp Business API Messaging

Whatsapp messageS

For compatibility purposes, Whatsapp Business API uses snake_case unlike the camelCase used in the rest of our omnichannel documentation.

You can use the Whatsapp API to send the following messages types:

1. Request syntax

2. Response syntax

3. Text message

4. Reaction Message

5. Media Message

6. Location Message

7. Contacts Message

8. Interactive Message

8. Send Reply Message

All of these message types, except for reaction messages, can be designated as a reply, which causes the delivered message to appear along with a contextual bubble displaying the content of the message that you are replying to.
The base URL for all API call strings is:

https://sozuri.net/api/v1/messaging

Request TO the Sozuri OmniChannel Whatsapp API

All whatsapp send message requests use the following request headers and authentication format. 
POST /api/v1/messaging
Content-Type: application/json
Authorization: Bearer Your_Project_API_KEY

All whatsapp SEND message requests use the following object format. 


{
  "project" : "YOUR_PROJECT_NAME", 
  "from": "",
  "to": "",
  "campaign": "YOUR_CAMPAIGN_NAME",
  "channel": "whatsapp",
  "recipient_type": "individual",
  "type": "",
  
  /* TEXT MESSAGES ONLY */
  "text": {}
  /* REACTION MESSAGES ONLY */
  "reaction": {}
  /* MEDIA MESSAGES ONLY. FOR EXAMPLE, FOR IMAGE MEDIA: */
  "image": {}
  /* LOCATION MESSAGES ONLY */
  "location": {}
  /* CONTACTS MESSAGES ONLY */
  "contacts": {}
  /* INTERACTIVE MESSAGES ONLY */
  "interactive": {}
}

Parameter Name Mandatory Type Description
project Yes String The name of the project that owns the apiKey making this request.
from Yes String The Whatsapp Business Number
channel Yes String "whatsapp"
recipient_type Yes String "individual"
campaign No String Name of the campaign you are sending the message for.
to Yes String A comma separated string of recipients’ phone numbers. Define the messages destination in the international mobile number format .E164 e.g "25472xx64287,25472289xx45".   NB: talkzuri API will attempt to format your numbers accordingly eg.0722-503-129 is formatted to 254722503129
type Yes String The type of message content. Valid values are: text, location, reaction, contacts, interactive, audio/document/image/sticker/video
text object No Object Text message contents.
reaction object No Object Reaction message contents.
audio, document, image, sticker, or video object No Object Media message contents.
location object No Object Location message contents.
contacts object No Object Contacts message contents.
interactive object No Object Interactive message contents.
apiKey - String The Project API Key. NB: Instead of having the apiKey in the body, it can alternatively be added as the Value of an Authorization header Bearer token instead. See its use in the Request header HERE

Sozuri Whatsapp Synchronous Response parameters for all message requests

Response FROM Sozuri OmniChannel API (synchronous)

The body of all the message response will be a JSON object containing the following fields: 
{
 "messageData": {
  "messages": 1
 },
"recipients": [
  {
     "message_id": "f659b9ba4d9551c39ca61498126da29f68a1c1e9",
     "to": "+254725164293",
     "status": "queued",
  }
 ]
}
Parameter Name Type Description
messageData String The eventual result of the sms request. It contains the count of sms: >
recipients String A list of recipients that you included in the request. Each recipient is a Map with the following fields
message_id String This is the unique talkzuri message ID returned in the response after the message is successfully accepted
status String Description of the status code eg. accepted, queued, sent, unknown_number. This is not indicative of the delivery status of the message.
to String The recipient mobile number

Sample text message request

POST Send Text Message Request 


curl -X  POST \
'https://sozuri.net/api/v1/messaging' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '
    {
        "project" : "YOUR_PROJECT_NAME",
        "from": "BUSINESS_PHONE_NUMBER",
        "channel": "whatsapp",
        "recipient_type": "individual",
        "campaign": "YOUR_CAMPAIGN_NAME",
        "to": "PHONE_NUMBER",
        "type": "text",
        "text": { // the text object
            "preview_url": false,  //set to true if you would like to add preview URL, add the preview_url field:
            "body": "MESSAGE_CONTENT"
        }
    }'

Sample Reaction message request


curl -X  POST \
'https://sozuri.net/api/v1/messaging' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '
    {
        "project" : "YOUR_PROJECT_NAME",
        "from": "BUSINESS_PHONE_NUMBER",
        "channel": "whatsapp",
        "recipient_type": "individual",
        "campaign": "YOUR_CAMPAIGN_NAME",
        "to": "PHONE_NUMBER",
        "type": "reaction",
        "reaction": {
            "message_id": "MESSAGE_ID",
            "emoji": "\uD83D\uDE00"
        }
    }'

Sample media message request

To send to send a media message. Use the type property to indicate the media asset's type (audio, document, image, sticker, or video) and the link property Your asset link must be on a publicly accessible server or the message will fail to send.

POST Send Media Message Request 


curl -X  POST \
'https://sozuri.net/api/v1/messaging' \
-H 'Authorization: Bearer apiKey' \
-H 'Content-Type: application/json' \
-d '
    {   
    "project" : "YOUR_PROJECT_NAME",
    "from": "BUSINESS_PHONE_NUMBER",
    "channel": "whatsapp",
    "recipient_type": "individual",
    "campaign": "YOUR_CAMPAIGN_NAME",
      "to": "PHONE_NUMBER",
      "type": "image",
      "image": {
        "link" : "https://IMAGE_URL"
      }
    }'

Sample Location message request

To send location messages, make a POST call and attach a message object with type=location. Then, add a location object.

POST Send Location Message Request 


curl -X  POST \
'https://sozuri.net/api/v1/messaging' \
-H 'Authorization: Bearer apiKey' \
-H 'Content-Type: application/json' \
-d '
    {   
    "project" : "YOUR_PROJECT_NAME",
    "from": "BUSINESS_PHONE_NUMBER",
    "channel": "whatsapp",
    "recipient_type": "individual",
    "campaign": "YOUR_CAMPAIGN_NAME",
      "to": "PHONE_NUMBER",
      "type": "location",
      "location": {
        "longitude": LONG_NUMBER,
        "latitude": LAT_NUMBER,
        "name": LOCATION_NAME,
        "address": LOCATION_ADDRESS
      }
    }'

Sample Contacts message request

To send contacts messages, make a POST call and attach a message object with type=contacts. Then, add a contacts object.

POST Send Contacts Message Request 


curl -X  POST \
'https://sozuri.net/api/v1/messaging' \
-H 'Authorization: Bearer apiKey' \
-H 'Content-Type: application/json' \
-d '
    {   
    "project" : "YOUR_PROJECT_NAME",
    "from": "BUSINESS_PHONE_NUMBER",
    "channel": "whatsapp",
    "recipient_type": "individual",
    "campaign": "YOUR_CAMPAIGN_NAME",
    "to": "PHONE_NUMBER",
    "type": "contacts",
    "contacts": [{
        "addresses": [{
            "street": "STREET",
            "city": "CITY",
            "state": "STATE",
            "zip": "ZIP",
            "country": "COUNTRY",
            "country_code": "COUNTRY_CODE",
            "type": "HOME"
            },
            {
            "street": "STREET",
            "city": "CITY",
            "state": "STATE",
            "zip": "ZIP",
            "country": "COUNTRY",
            "country_code": "COUNTRY_CODE",
            "type": "WORK"
            }],
        "birthday": "YEAR_MONTH_DAY",
        "emails": [{
            "email": "EMAIL",
            "type": "WORK"
            },
            {
            "email": "EMAIL",
            "type": "HOME"
            }],
        "name": {
            "formatted_name": "NAME",
            "first_name": "FIRST_NAME",
            "last_name": "LAST_NAME",
            "middle_name": "MIDDLE_NAME",
            "suffix": "SUFFIX",
            "prefix": "PREFIX"
        },
        "org": {
            "company": "COMPANY",
            "department": "DEPARTMENT",
            "title": "TITLE"
        },
        "phones": [{
            "phone": "PHONE_NUMBER",
            "type": "HOME"
            },
            {
            "phone": "PHONE_NUMBER",
            "type": "WORK",
            "wa_id": "PHONE_OR_WA_ID"
            }],
        "urls": [{
            "url": "URL",
            "type": "WORK"
            },
            {
            "url": "URL",
            "type": "HOME"
            }]
        }]
    }'

Sample Interactive message request

Interactive messages include List Messages and Reply Buttons. To send interactive messages, make a POST call and attach a message object with type=interactive. Then, add a interactive object.

POST Send interactive Message Request 


curl -X  POST \
'https://sozuri.net/api/v1/messaging' \
-H 'Authorization: Bearer apiKey' \
-H 'Content-Type: application/json' \
-d '
    {   
    "project" : "YOUR_PROJECT_NAME",
    "from": "BUSINESS_PHONE_NUMBER",
    "channel": "whatsapp",
    "recipient_type": "individual",
    "campaign": "YOUR_CAMPAIGN_NAME",
    "to": "PHONE_NUMBER",
    "type": "interactive",
    "interactive": {
      "type": "list",
      "header": {
        "type": "text",
        "text": "HEADER_TEXT"
      },
      "body": {
        "text": "BODY_TEXT"
      },
      "footer": {
        "text": "FOOTER_TEXT"
      },
      "action": {
        "button": "BUTTON_TEXT",
        "sections": [
          {
            "title": "SECTION_1_TITLE",
            "rows": [
              {
                "id": "SECTION_1_ROW_1_ID",
                "title": "SECTION_1_ROW_1_TITLE",
                "description": "SECTION_1_ROW_1_DESCRIPTION"
              },
              {
                "id": "SECTION_1_ROW_2_ID",
                "title": "SECTION_1_ROW_2_TITLE",
                "description": "SECTION_1_ROW_2_DESCRIPTION"
              }
            ]
          },
          {
            "title": "SECTION_2_TITLE",
            "rows": [
              {
                "id": "SECTION_2_ROW_1_ID",
                "title": "SECTION_2_ROW_1_TITLE",
                "description": "SECTION_2_ROW_1_DESCRIPTION"
              },
              {
                "id": "SECTION_2_ROW_2_ID",
                "title": "SECTION_2_ROW_2_TITLE",
                "description": "SECTION_2_ROW_2_DESCRIPTION"
              }
            ]
          }
        ]
      }
    }
  }'

Interactive reply button 



curl -X  POST \
'https://sozuri.net/api/v1/messaging' \
-H 'Authorization: Bearer apiKey' \
-H 'Content-Type: application/json' \
-d '
    {   
    "project" : "YOUR_PROJECT_NAME",
    "from": "BUSINESS_PHONE_NUMBER",
    "channel": "whatsapp",
    "recipient_type": "individual",
    "campaign": "YOUR_CAMPAIGN_NAME",
    "to": "PHONE_NUMBER",
    "type": "interactive",
    "interactive": {
      "type": "button",
      "body": {
        "text": "BUTTON_TEXT"
      },
      "action": {
        "buttons": [
          {
            "type": "reply",
            "reply": {
              "id": "UNIQUE_BUTTON_ID_1",
              "title": "BUTTON_TITLE_1"
            }
          },
          {
            "type": "reply",
            "reply": {
              "id": "UNIQUE_BUTTON_ID_2",
              "title": "BUTTON_TITLE_2"
            }
          }
        ]
      }
    }
  }'

Sample Reply message request

You can send any message as a reply to a previous message in a conversation by including the previous message's ID in the context object. The recipient will receive the new message along with a contextual bubble that displays the previous message's content.

POST Send interactive Message Request 


curl -X  POST \
'https://sozuri.net/api/v1/messaging' \
-H 'Authorization: Bearer apiKey' \
-H 'Content-Type: application/json' \
-d '
    {   
    "project" : "YOUR_PROJECT_NAME",
    "from": "BUSINESS_PHONE_NUMBER",
    "channel": "whatsapp",
    "campaign": "YOUR_CAMPAIGN_NAME",
    "context": {
        "message_id": "MESSAGE_ID"
      },    
    "to": "PHONE_NUMBER",
    "type": "text",
    "text": {
     "preview_url": False,
     "body": "your-text-message-content"
   }
 }'