WhatsApp Chat API

This section explains how you can use QuickReply.ai’s APIs to build a chatbot with your end users over WhatsApp.

Overview

QuickReply.ai offers a native AI builder (chatbot builder) that covers most use cases efficiently. For typical needs, this built-in tool provides an easy-to-use and effective solution. The WhatsApp Chat API should be used primarily for scenarios requiring a custom proprietary chatbot with specific functionalities that cannot be achieved with the native builder. This can also be used if you wish to integrate a Generative AI based chatbot on to WhatsApp channel over QuickReply.ai

How It Works

  • Disable AI Builder (chatbot builder)

    1. Firstly, you will need to disable the AI builder.

    2. To disable AI builder, you can delete all nodes from these playbooks - Default, Fallback and Transfer. In each of the playbooks, add a End node at the start.

    3. Alternatively you can write to help@quickreply.ai get the AI Builder disabled.

  • Receiving Messages:

    • Incoming messages from users are received through a webhook configured to handle these events.

  • Sending Messages:

    • To send a message to a WhatsApp user, make a POST request to the Send Message endpoint with the required message details.

  • Handling Message Status Updates:

    • Track the status of sent messages (e.g., delivered, read) via a webhook that provides real-time updates.

API Endpoints

Receive Message

To receive messages sent by users on your WhatsApp integrated with QuickReply.ai, you will need to configure a webhook url in your QuickReply.ai account.

POST [Your Webhook URL]

Webhook endpoint for receiving incoming messages from WhatsApp users.

Headers

Param
Value

Content-Type*

application/json

Body

Param
Type
Description

id

string

Unique message id

phone

string

Phone no. in E164 Format

reply_to

string

Id of the message replied to (if user replied to a particular message)

msg_time

number

Time in milli-seconds

payload

JSON Object

Payload Object is explained below

Payload Object

Param
Type
Description

_type

string

one of USER_TEXT ,USER_FILE ,USER_LIST_REPLY or USER_BUTTON_REPLY

text

string

Text sent by user (in case of USER_TEXT)

name

string

Name of file (in case of USER_FILE)

contentType

string

Content type of file (in case of USER_FILE)

caption

string

Text sent by user

(in case of USER_FILE)

status

string

"SUCCESS"

path

string

URL of the file

(in case of USER_FILE)

This URL gets expired after an year, so it is recommended to download the file on your server

preview

JSON Object

Preview Object

(in case of reply message or message containing link)

Preview Object

Param
Type
Description

replyPreview

Object

Reply Preview Object (When message is reply to another message)

urlPreview

Object

URL Preview Object (When message contains URL)

If a message has both reply to a message and a url, only the replyPreview will come.

Reply Preview Object

Param
Type
Description

header

Object

Header Object Fields

For replies to messages containing media such as videos, images, documents, or audio:

  1. type: Specifies the type of header (e.g., image, video, document).

  2. previewImage: URL of the preview image, if available.

body

Object

Body Fields:

  • text: Original text message to which this reply is given.

meta

Object

Metadata

  • userId: The user ID assigned by QuickReply.ai.

  • repliedMessageId: Internal message ID used by WhatsApp, typically not needed for user reference.

URL Preview Object

Param
Type
Description

url

string

Complete URL for which preview is included

domain

string

domain of above URL

title

string

title shown to user in the preview

sitename

string

name of website (Currently not shown to user in WhatsApp)

description

string

description shown to user in the preview

image

Object

Image Details

  • url: url of Image

  • width: width of Image

  • Height: height of Image

Sample Payload objects

Text message sent by user
{
  "id": "dq7HoK7y4yRMTEpj7_msg",
  "phone": "+9199XXXXXXXX1",
  "msg_time": 1725541364563,
  "payload": {
    "text": "HI",
    "_type": "USER_TEXT"
  }
}
Image message having a caption
{
  "id": "HPXKPpoDpG6Ze3zbA_msg",
  "phone": "+919XXXXXXXX1",
  "msg_time": 1725543260528,
  "payload": {
    "_type": "USER_FILE",
    "path": "https://d2gxu7oczk95hf.cloudfront.net/company/XXXXXXX/chatusers/XXXXXXX/1725XXXXX543260344_original.jpeg?Expires=1757079260&Key-Pair-Id=APKAJJB3QB7QKGWPAGUQ&Signature=HiBVkaV6-kUBTq9zkpcUgGM3hF3rTuby3JQJgUDe55adCyiP~mX48RA2MYHYRrIGtpfb3am3XLNQilCRogwclU75Fg6citpzMGhtM0xrs7zdpRp0dNCgURjDF~6DOMk~dj50WMJWiZDKUBrha7gUaumAof~Pdc~oFCLBXhgHimuzisaCWcUtgXDxY3fC~9Q6hQdo5-6X2k6XdZDR6XHqlS01~zfcJZvABHjORVAa4DYve5YQxMpdTnVSg8iGiYpOybIoWd7nFqj2j~niZD-CESrCb87rNNu23TwNU4qVqzYTQF6C4LMJf9W1HFvZ8FKvo-VO46SBPEsOq6Qb~TZJ6g__",
    "name": "1725543260235",
    "status": "SUCCESS",
    "contentType": "image/jpeg",
    "audioText": "",
    "caption": "Team photo"
  } 
}
Image message without any caption
{
  "id": "ZhzcpjQa3sgDkdM28_msg",
  "phone": "+919XXXXXXX1",
  "msg_time": 1725543296987,
  "payload": {
    "_type": "USER_FILE",
    "path": "https://d2gxu7oczk95hf.cloudfront.net/company/XXXXXXX/chatusers/XXXXXXX/172XXXXX6843_original.jpeg?Expires=1757079297&Key-Pair-Id=APKAJJB3QB7QKGWPAGUQ&Signature=EfZWoc1l6nRTDOusLzVfI4jJxmrT4COkbCJ7T0aMlUk4e4lPVQxoZ5Fn7NCQLwMieglyMnZ0OHzgKdKBK3a02Jqjc-jUgK3w4bMRtU6Wanm~hBVGaLyhf3caqdbKPguM66K0GEAyuEegXJbUb434LGP8DWq0yCSIWGaXIDA4OjlGdujPXJMc9t0qJfIF4v8VZgT2~Us5j~FdSuiU8mr0LgBtFuvxTLVnSy~3~NrSSiSW5luZAIeRSfWLq6wYGkkVZTJu4Hg9-qJiZ9122GIcgGzlqks1maI1UZi9sn2--cgMe-fDw2z-HLiFTQ-rSQB1qlH4C9z4ujwf-9-MgfXrXg__",
    "name": "1725543296811",
    "status": "SUCCESS",
    "contentType": "image/jpeg",
    "audioText": ""
  }
}
Document with caption
{
  "id": "WX6Htqh4W6329JPX6_msg",
  "phone": "+919XXXXXXX1",
  "msg_time": 1725543340052,
  "payload": {
    "path": "https://d2gxu7oczk95hf.cloudfront.net/company/XXXXXX/chatusers/XXXXXX/1725543339425_original.pdf?Expires=1757079340&Key-Pair-Id=APKAJJB3QB7QKGWPAGUQ&Signature=WnZFt~bU4g56eFQsNC7mdyLf-BconFgWDYkA3BTP~pUDSdhvqRwBN7DEg-jvHUDJyRg6acB2moqnXmwKta2dtmQJXwShS~9XXTujCSLoH23VqEYz70ZUXBUKLo1i1byInjoKdYBT-QMQamzMzh9NJ0uEGRfD9MO1s119jSR7F~J11ppz2DDlro-lwe6Ci3CBG2j-~Sj6CSmk~ICf1eyp4eL7fsVaZZG2UK2tDA5XPF~Zt-h3b2YGhsXB-lMa1q4IZ8vYIwPxuTu5G~5oR7PKo3QbY2kAOu0QJhVZUXd7eUN-KGHUV-OUThlKtSg3M85YR-cIAkr1RlO9WsyJ4MulfA__",
    "_type": "USER_FILE",
    "name": "Documentation_QR_2024.pdf",
    "status": "SUCCESS",
    "contentType": "application/pdf",
    "audioText": "",
    "caption": "Documentation for QuickReply.ai platform"
  }
}
Video with caption
{
  "id": "gC8LSjZEWyZgkDYLs_msg",
  "phone": "+919XXXXXXX1",
  "msg_time": 1725543511327,
  "payload": {
    "path": "https://d2gxu7oczk95hf.cloudfront.net/company/XXXXXXX/chatusers/XXXXXXX/1725XXXXX078_original.mp4?Expires=1757079511&Key-Pair-Id=APKAJJB3QB7QKGWPAGUQ&Signature=B9qyHaK4GJakJ8dcK2BJdE-9RdRJrZLfL5XofrQOpwdNwXtNvmca90juytlgbO-ZczqH6MeqEj5rUBw8K7i2-ZAR8TGpmoJz9LK5E5dHUyzmi863rdyM8LdcgsqkhaD0I6HUW5r1M3bxXHVVQ3082SCfel-ja4FWps~5KC0FgovONl5nWBQYfdsVf2A66Cz8jHjn0KywmMOV7hIQ7hABYBK18c3i80Bl5SOF2d4Gi1WblGBCXMCQVN1YtCGnm7qYKykdRUg1wmOFOylgp3WjO8Fq2Q0z-WVO1BM6RYnMPPqFGR0Pp5tOJJgYehsvBPxvVKU5aYaURONVlF80gLbbVg__",
    "_type": "USER_FILE",
    "name": "1725543511019",
    "status": "SUCCESS",
    "contentType": "video/mp4",
    "audioText": "",
    "caption": "Screen recording example"
  }
}
Reply to a text message with a text message
{
  "id": "PNRNu5GjgcdJgiaK2_msg",
  "phone": "+919XXXXXXX1",
  "msg_time": 1725543565950,
  "reply_to": "WSvFqApKjeRcS3KBM_msg"
  "payload": {
    "text": "hello reply message",
    "_type": "USER_TEXT",
    "preview": {
      "replyPreview": {
        "body": {
          "text": "hi this is original message"
        },
        "meta": {
          "userId": "zvYeDsXJdpCW6fC2e_ag",
          "repliedMessageId": "wamid.HBgMOTE5OTIyNTY0MzExFQIAERgSNDI0N0MwRTk0MDQ1RURDRTY1AA=="
        }
      }
    }
  }
}

Reply to a text message with an Image having caption
{
  "id": "FHc5F7coHPKyrtc6p_msg",
  "phone": "+919XXXXXXX1",
  "msg_time": 1725543650636,
  "reply_to": "ZdNfzpyzbyGRKarc8_msg"
  "payload": {
    "path": "https://d2gxu7oczk95hf.cloudfront.net/company/XXXXXXX/chatusers/XXXXXXX/1725543650523_original.jpeg?Expires=1757079650&Key-Pair-Id=APKAJJB3QB7QKGWPAGUQ&Signature=dCbDRQ8tn3gM3~ZZ0lDCIErFicsof5~1FS4~5v9-wfMmNWGX7qdHJXukMNCjbmy0JVtfEdxPQaToe5Vy7LBypytEsuKOGmtomkPEtJHp2MNLYQRZ8b3hiYj~wVcsRLGc7JePs4X-07MSQ9F8jb9CjIQ~x15ggw-usubV5UukOQOhJZXfFbkEuueltIzgsEgugN6bLmChnzeYihC2Gi9lPhbmmke-Wy6hU3AivV0T0N7LznnSm7gsa3bW4YnqNnRqcpAt4z3gQ9-bWyKikXAaVLpZ8ahpufDZEjHuN9ys9cHKnnWgim7NDNeMw6aTBTPg3-PHXlgZaTdtf1BNcEzp6w__",
    "_type": "USER_FILE",
    "name": "1725543650311",
    "status": "SUCCESS",
    "contentType": "image/jpeg",
    "audioText": "",
    "caption": "screenshot",
    "preview": {
      "replyPreview": {
        "body": {
          "text": "Hi this is original message"
        },
        "meta": {
          "userId": "zvYeDsXJdpCW6fC2e_ag",
          "repliedMessageId": "wamid.HBgMOTE5OTIyNTY0MzExFQIAERgSNjQ2N0Y1MDFDRkQxQUNFMjZGAA=="
        }
      }
    }
  }
}
Text message having a URL
{
  "id": "MM9tmHwuXGbRiHHdj_msg",
  "phone": "+919XXXXXXX1",
  "msg_time": 1725545036650,
  "payload": {
    "text": "https://x.com/XDevelopers/status/1740386052446060725 check this tweet",
    "_type": "USER_TEXT",
    "preview": {
      "urlPreview": {
        "url": "https://x.com/XDevelopers/status/1740386052446060725",
        "domain": "x.com",
        "title": "Developers (@XDevelopers) on X",
        "sitename": "X (formerly Twitter)",
        "description": "Calling all #developers! 📣\n\nInnovate with our real-time and historical data on the X API.\n\nGet started with Pro👇",
        "image": {
          "url": "https://pbs.twimg.com/profile_images/1683501992314798080/xl1POYLw_200x200.jpg",
          "width": "80",
          "height": "80"
        }
      }
    }
  }
}

Send Message

POST https://app.quickreply.ai/api/whatsapp/send-session-message

Sends a message to a specified WhatsApp user.

  • You can send message only if user has sent at least one message in the last 24 hours, otherwise message sending will fail.

  • If you wish to initiate a conversation from your end, you should send Template Message with CTA buttons. If user replies, the session will start and you will be able to send messages.

Headers

Param
Type
Value
Description

client-id*

string

<client id>

You can find client-id of your account in Settings > Developers > API credentials

secret-key*

string

<secret key>

You can find client-id of your account in Settings > Developers > API credentials

Content-Type*

string

application/json

Body

Param
Type
Value
Description

to*

string

<phone_number>

Phone no. in E164 Format

payload*

JSON object

<payload object>

Payload object is explained below

payload

Field
Type
Value
Description

_type*

string

AGENT_TEXT

Currently only text is supported. It doesn’t limit you from sending media using fields below

text

string

<text to send>

Message which is being sent to the user

img

url

URL of image

Image should be publicly accessible via URL. Max 5MB is allowed

video

url

URL of video

Video should be publicly accessible via URL. Max 16MB is allowed

audio

url

URL of audio

Audio should be publicly accessible via URL. Max 16MB is allowed

document

object

{ "link": "<url>", "filename":"<filename>" }

  1. url: Document should be publicly accessible via URL. Max 16MB is allowed

  2. filename: Filename to be displayed in WhatsApp

  • At a time, only one of the img, video, audio or document field can be supplied.

  • Sending media is optional, and you can send only text as well.

Example - 

curl --location 'https://app.quickreply.ai/api/whatsapp/send-session-message' \
--header 'client-id: <client-id>' \
--header 'secret-key: <client-secret>' \
--header 'Content-Type: application/json' \
--data '{
    "to": "+9196XX68XXXX",
    "payload" : {
        "text":"hi",
        "_type": "AGENT_TEXT"
    }
}'

Response

Response is a JSON object with the following structure

Param
Type
Description

id

string

unique message id if message is sent. null if scheduled

state

string

One of the following 1. SENT - When message is sent successfully. 2. NOT_SENT - When an error occurs while sending message. at WhatsApp end 3. SCHEDULED - When you call campaign API which schedules message to be sent in future instead of sending immediately.

reason

string

When message is not sent, Reason for NOT_SENT

Example

{
    "id": "WSvFqApKjeRcS3KBM_msg",
    "state": "SENT"
}

Message Status Update

To receive messages delivery reports you will need to configure a webhook url in your QuickReply.ai account.

POST [Your Webhook URL]

Webhook endpoint for receiving message status updates from WhatsApp users.

Body

Param
Type
Description

id

string

unique message id

event

string

one of SENT DELIVERED READ

How to Configure Webhooks?

To configure Webhooks, write to help@quickreply.ai and our support team will assist you with setting up the webhooks.

PreviousSync Contacts to CRM APINextSend Template API

Last updated