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)
Firstly, you will need to disable the AI builder.
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.
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)
{"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" } } } }}
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.
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"}
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 SENTDELIVEREDREAD
How to Configure Webhooks?
To configure Webhooks, write to help@quickreply.ai and our support team will assist you with setting up the webhooks.