Use the POST /message endpoint to send a message to a user

​
Send a message on WhatsApp

Regular messages

Here is a sample code to send a simple text message as a response to the user initiated conversation.

Please checkout Send Message reference section to know more about the request fields

curl --request POST \ --url https://chat.zoko.io/v2/message \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --data '{"channel":"whatsapp","recipient":"919876543210", "type":"text","message":"Hi Greenaro,\nHow can I help you today?"]}' `

Channel Guidelines and Restrictions

Please follow the guidelines to send a message to a user. Typically, each channel will have their own restrictions in sending a conversational message to a customer.

For example, WhatsApp allows Business Accounts to send messages only for 24 hours proceeding the last message from the customer.

​
Send a template message on WhatsApp

A Template message, is one which has a text body with fillable placeholders.

A simple template message

Here is a sample code to send a regular text template named shipping_01 that has 2 placeholders

  • order number
  • tracking url
curl --request POST \
  --url https://chat.zoko.io/v2/message \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{"channel":"whatsapp","recipient":"919876543210",
  "type":"template","templateId":"shipping_01",
  "templateArgs":["Z7422","https://zoko.io/order/status/Z7422"]}'

​
Send a rich template message on WhatsApp

A Rich Template is a message which has a media header and a text body. Imagine this like a template message with a media (image, document or video) header.

A simple rich template message

Here is a sample code to send a rich template named greeting_with_header_image_01 that has 3 placeholders

  • image header
  • customer name
  • business name
curl --request POST \
  --url https://chat.zoko.io/v2/message \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{"channel":"whatsapp","recipient":"919876543210",
  "type":"richTemplate", "templateId":"greeting_with_header_image_01", 
  "templateArgs":["<header image url>","Jane", "Zoko Gardens"]}'

​
Send a button template message on WhatsApp

This the next level of templates. Imagine a rich template with interactive buttons. That’s a Button Template message!

A typical button template message

Here is a sample code to send a button template named greet_with_options_01 that has 6 placeholders

  • image header
  • customer name
  • business name
  • payload for button 1
  • payload for button 2
  • payload for button 3
curl --request POST \
  --url https://chat.zoko.io/v2/message \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{"channel":"whatsapp","recipient":"919876543210",
  "type":"buttonTemplate","templateId":"greet_with_options_01",
  "templateArgs":["<header image url>","Jane","Zoko Gardens",
  "user_clicked_schedule_demo","user_clicked_agent",
  "user_clicked_more_options"]}'

​
Send an Interactive Button Message on WhatsApp

An Interactive Button message is similar to a Button Template except this is not a template and hence doesn’t need an approval. But this type of message can only be sent as a reply - during the 24 hours window of a chat.

Messages including up to 3 options —each option is a button. This type of message offers a quicker way for users to make a selection from a menu when interacting with a business. Reply buttons have the same user experience as Button Template messages.

Interactive Button Message can have an optional header, a text body and an optional footer.

curl --request POST \
     --url https://chat.zoko.io/v2/message \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'apikey: <api-key>' \
     --data '
        {
     "channel": "whatsapp",
     "recipient": "919876543210",
     "type": "interactive_button",
     "interactiveButton":
        {
        "header": {
          "type": "document", // text || image || document || video
          "filename": "brochure.pdf",
          "text": "http://www.africau.edu/images/default/sample.pdf"
        },
        "body": {
          "text": "Thanks for your feedback. Do you want to chat with an agent?"
        },
        "footer": {
          "text": "Powered by Zoko"
        },
        "buttons": [
          {
            "reply": {
              "payload": "feedback_yes",
              "title": "Yes"
            }
          },
          {
            "reply": {
              "payload": "feedback_no",
              "title": "No"
            }
          }
        ]
            }
        }'

​
Send Interactive List Message on WhatsApp

Messages including a menu of up to 10 options. This type of message offers a simpler and more consistent way for users to make a selection when interacting with a business.

List Messages are best for presenting several options, such as:

  • A customer care or FAQ menu
  • A take-out menu
  • Selection of nearby stores or locations
  • Available reservation times
  • Choosing a recent order to repeat
curl --request POST \
  --url https://chat.zoko.io/v2/message \
  --header 'accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'apikey: <api-key>' \
  --data 
  '{
    "channel": "whatsapp",
    "recipient": "919876543210",
    "type": "interactive_list",
    "interactiveList": {
        "header": {
            "text": "Faux Menu"
        },
        "body": {
            "text": "Thanks for your feedback. Do you want to chat with an agent?"
        },
        "footer": {
            "text": "Powered by Zoko"
        },
        "list": {
            "title": "Menu",
            "sections": [
                {
                    "title": "Seafood",
                    "items": [
                        {
                            "title": "Crab Bisque",
                            "description": "Not enough words to describe it",
                            "payload": "sea_1"
                        }
                    ]
                },
                {
                    "title": "Chimkin",
                    "items": [
                        {
                            "title": "Chimkin Kebab",
                            "description": "Skewed n juicy",
                            "payload": "chick_1"
                        },
                        {
                            "title": "Chimkin Roast",
                            "description": "Roasted the life out of it",
                            "payload": "chick_2"
                        },
                        {
                            "title": "Chimkin Tandoori",
                            "description": "From the pits of hell",
                            "payload": "chick_3"
                        }
                    ]
                }
            ]
        }
    }
}'

​
Response for Send Message

Response will include the message id and the status of the message.

JSON
{
  "status": "200",
  "statusText": "Accepted",
  "messageId": "068a169a-f1fe-11ea-9b75-42010a67e00f"
}

Message response status accepted means that the message has been accepted by the channel (WhatsApp in the above examples). It just means the request seems valid and will be processed.

The actual delivery updates on the message - if and when it was delivered, failed, read or seen etc will come later as and when it happens. We do track those and display them correctly on the Zoko Chat Dashboard.

But if you are an API only user, you would need the help of webhooks to get notified of those updates.

OverviewMessage History