Send a message

How to send a message to a user using the API

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

Send a message on WhatsApp

Regular messagesRegular messages

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?"]}'
const request = require('request');

const options = {
  method: 'POST',
  url: 'https://chat.zoko.io/v2/message',
  headers: {accept: 'application/json', 'content-type': 'application/json'},
  body: {
    channel: 'whatsapp',
    recipient: '919876543210',
    type: 'text',
    message: 'Hi Greenaro,\nHow can I help you today?'
  },
  json: true
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
import requests

url = "https://chat.zoko.io/v2/message"

payload = {
    "channel": "whatsapp",
    "recipient": "919876543210",
    "type": "text",
    "message": "Hi Greenaro,\nHow can I help you today?"
}
headers = {
    "accept": "application/json",
    "content-type": "application/json"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)
require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://chat.zoko.io/v2/message")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Post.new(url)
request["accept"] = 'application/json'
request["content-type"] = 'application/json'
request.body = "{\"channel\":\"whatsapp\",\"recipient\":\"919876543210\",
\"type\":\"text\",\"message\":\"Hi Greenaro, how can I help you today\"}"

response = http.request(request)
puts response.read_body

📘

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 messageA simple template message

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"]}'
const request = require('request');

const options = {
  method: 'POST',
  url: 'https://chat.zoko.io/v2/message',
  headers: {accept: 'application/json', 'content-type': 'application/json'},
  body: {
    channel: 'whatsapp',
    recipient: '919876543210',
    type: 'template',
    templateId: 'shipping_01',
    templateArgs: ['Z7422', 'https://zoko.io/order/status/Z7422']
  },
  json: true
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
import requests

url = "https://chat.zoko.io/v2/message"

payload = {
    "channel": "whatsapp",
    "recipient": "919876543210",
    "type": "template",
    "templateId": "shipping_01",
    "templateArgs": ["Z7422", "https://zoko.io/order/status/Z7422"]
}
headers = {
    "accept": "application/json",
    "content-type": "application/json"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)
require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://chat.zoko.io/v2/message")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Post.new(url)
request["accept"] = 'application/json'
request["content-type"] = 'application/json'
request.body = "{\"channel\":\"whatsapp\",\"recipient\":\"919876543210\",
\"type\":\"template\",\"templateId\":\"shipping_01\",
\"templateArgs\":[\"Z7422\",\"https://zoko.io/order/status/Z7422\"]}"

response = http.request(request)
puts response.read_body



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 messageA simple rich template message

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"]}'
const request = require('request');

const options = {
  method: 'POST',
  url: 'https://chat.zoko.io/v2/message',
  headers: {
    accept: 'application/json',
    'content-type': 'application/json',
    apikey: '<apikey>'
  },
  body: {
    channel: 'whatsapp',
    recipient: '919876543210',
    type: 'richTemplate',
    templateId: 'greeting_with_header_image_01',
    templateArgs: ['<header-image-url>', 'Jane', 'Zoko Gardens']
  },
  json: true
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
import requests

url = "https://chat.zoko.io/v2/message"

payload = {
    "channel": "whatsapp",
    "recipient": "919876543210",
    "type": "richTemplate",
    "templateId": "greeting_with_header_image_01",
    "templateArgs": ["<header image url>", "Jane", "Zoko Gardens"]
}
headers = {
    "accept": "application/json",
    "content-type": "application/json",
    "apikey": "<apikey>"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)
require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://chat.zoko.io/v2/message")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Post.new(url)
request["accept"] = 'application/json'
request["content-type"] = 'application/json'
request["apikey"] = '<apikey>'
request.body = "{\"channel\":\"whatsapp\",\"recipient\":\"919876543210\", \"type\":\"richTemplate\",\"templateId\":\"greeting_with_header_image_01\", \"templateArgs\":[\"<header image url>\",\"Jane\",\"Zoko Gardens\"]}"

response = http.request(request)
puts response.read_body

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 messageA typical 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"]}'
const request = require('request');

const options = {
  method: 'POST',
  url: 'https://chat.zoko.io/v2/message',
  headers: {accept: 'application/json', 'content-type': 'application/json'},
  body: {
    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'
    ]
  },
  json: true
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
import requests

url = "https://chat.zoko.io/v2/message"

payload = {
    "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"],
}
headers = {
    "accept": "application/json",
    "content-type": "application/json"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)
require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://chat.zoko.io/v2/message")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Post.new(url)
request["accept"] = 'application/json'
request["content-type"] = 'application/json'
request.body = "{\"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\"]}"

response = http.request(request)
puts response.read_body



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"
            }
          }
        ]
            }
        }'
const request = require('request');

const options = {
  method: 'POST',
  url: 'https://chat.zoko.io/v2/message',
  headers: {accept: 'application/json', 'content-type': 'application/json'},
  body: {
    channel: 'whatsapp',
    recipient: '919876543210',
    type: 'interactive_button',
    interactiveButton: { 
        header : { 
        type : "document", 
        text: "http://www.africau.edu/images/default/sample.pdf",
        filename : "brochure.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" 
            }
          }
        ]
       },
  json: true
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
import requests

url = "https://chat.zoko.io/v2/message"

payload = {
    "channel": "whatsapp",
    "recipient": "919876543210",
    "type": "interactive_button", 
    "interactiveButton": { 
      "header" : { 
        "type": "document", 
        "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" }}
      ]
    } 
}
headers = {
    "accept": "application/json",
    "content-type": "application/json"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)



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"
                        }
                    ]
                }
            ]
        }
    }
}'
const request = require('request');

const options = {
  method: 'POST',
  url: 'https://chat.zoko.io/v2/message',
  headers: {accept: 'application/json', 'content-type': 'application/json'},
  body: {
    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"
                        }
                    ]
                }
            ]
        }
    },
  json: true
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});



Response for Send Message

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

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

📘

TIP

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.


Did this page help you?