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 [e-mail] 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: type: Specifies the type of header (e.g., image, video, document). 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>" }	url: Document should be publicly accessible via URL. Max 16MB is allowed 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

200

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"
}

400

Response is a JSON object with the following structure

Param	Type	Value
error	string	error message

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 [e-mail] and our support team will assist you with setting up the webhooks.