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

Field

Value

Content-Type*

application/json

Body

Field

Type

Description

id

string

Unique message id

phone

string

Phone no. in E164 Format starting + with country code and phone number without any space or other chars

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

messageBy

string

Fixed value USER

name

string

Name of user set in QuickReply

string

Email of user if set in QuickReply

Payload Object

Field

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

Field

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

Field

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.

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

Quick Reply button click (Selecting button on message having QuickReply buttons)

{
  "id": "fqh8oAuTJHtQ6qoRp_msg",
  "payload": {
    "text": "Know More",
    "_type": "USER_BUTTON_REPLY",
    "preview": {
      "replyPreview": {
        "body": {
          "text": "Please choose an Option."
        },
        "meta": {
          "userId": "69ca553a82938eb329832f60_ag",
          "repliedMessageId": "mz2SQ9zT4ifNAJwez_msg"
        }
      }
    },
    "msg_id": "mz2SQ9zT4ifNAJwez_msg"
  },
  "msg_time": 1776845556000,
  "reply_to": "mz2SQ9zT4ifNAJwez_msg",
  "phone": "+91XXXXXXXXXX",
  "name": "James",
  "messageBy": "USER"
}

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

Field

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

Required for

Description

_type

string

All messages

Use AGENT_TEXT for text and media, AGENT_TRIGGER_QUESTION for quick replies, WA_LIST for list messages, or AGENT_LOCATION for locations.

text

string

Text, image, document, video, quick reply, and list

Message text or media caption. It is not used for audio or location messages.

img

URL

Image

Public image URL. Maximum size: 5 MB.

video

URL

Video

Public video URL. Maximum size: 16 MB.

audio

URL

Audio

Public audio URL. Maximum size: 16 MB. Audio messages have no caption.

document

object

Document

Provide link as a public URL and filename as the displayed filename. Maximum size: 16 MB.

options

array

Quick reply

Up to three objects, each with a text field.

title

string

List

List message header.

list_title

string

List

Label for the list button.

sections

array

List

Sections with section_name and options. Each option contains text and an optional description.

name, address

string

Location

Location name and address.

latitude, longitude

number

Location

Location coordinates.

Supply only one media field: img, video, audio, or document.

Examples

All examples use the same endpoint and authentication headers.

Plain text

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

Image with caption

curl --location 'https://app.quickreply.ai/api/whatsapp/send-session-message' \
  --header 'client-id: <CLIENT_ID>' \
  --header 'secret-key: <SECRET_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "to": "<PHONE_NUMBER>",
    "payload": {
      "_type": "AGENT_TEXT",
      "text": "Image caption",
      "img": "https://example.com/image.png"
    }
  }'

Document with caption

curl --location 'https://app.quickreply.ai/api/whatsapp/send-session-message' \
  --header 'client-id: <CLIENT_ID>' \
  --header 'secret-key: <SECRET_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "to": "<PHONE_NUMBER>",
    "payload": {
      "_type": "AGENT_TEXT",
      "text": "Document caption",
      "document": {
        "link": "https://example.com/file.pdf",
        "filename": "file.pdf"
      }
    }
  }'

Quick reply buttons

curl --location 'https://app.quickreply.ai/api/whatsapp/send-session-message' \
  --header 'client-id: <CLIENT_ID>' \
  --header 'secret-key: <SECRET_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "to": "<PHONE_NUMBER>",
    "payload": {
      "_type": "AGENT_TRIGGER_QUESTION",
      "text": "Pick one",
      "options": [
        { "text": "Option A" },
        { "text": "Option B" },
        { "text": "Option C" }
      ]
    }
  }'

List message

curl --location 'https://app.quickreply.ai/api/whatsapp/send-session-message' \
  --header 'client-id: <CLIENT_ID>' \
  --header 'secret-key: <SECRET_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "to": "<PHONE_NUMBER>",
    "payload": {
      "_type": "WA_LIST",
      "title": "List title",
      "text": "Body text shown above the list",
      "list_title": "View options",
      "sections": [
        {
          "section_name": "Products",
          "options": [
            { "text": "Product A", "description": "First product" },
            { "text": "Product B", "description": "Second product" }
          ]
        },
        {
          "section_name": "Services",
          "options": [
            { "text": "Service X", "description": "Premium service" }
          ]
        }
      ]
    }
  }'

Location

curl --location 'https://app.quickreply.ai/api/whatsapp/send-session-message' \
  --header 'client-id: <CLIENT_ID>' \
  --header 'secret-key: <SECRET_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "to": "<PHONE_NUMBER>",
    "payload": {
      "_type": "AGENT_LOCATION",
      "name": "Location name",
      "address": "Mumbai, Maharashtra, India",
      "latitude": 19.0760,
      "longitude": 72.8777
    }
  }'

Video with caption

curl --location 'https://app.quickreply.ai/api/whatsapp/send-session-message' \
  --header 'client-id: <CLIENT_ID>' \
  --header 'secret-key: <SECRET_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "to": "<PHONE_NUMBER>",
    "payload": {
      "_type": "AGENT_TEXT",
      "text": "Video caption",
      "video": "https://example.com/video.mp4"
    }
  }'

Audio

curl --location 'https://app.quickreply.ai/api/whatsapp/send-session-message' \
  --header 'client-id: <CLIENT_ID>' \
  --header 'secret-key: <SECRET_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "to": "<PHONE_NUMBER>",
    "payload": {
      "_type": "AGENT_TEXT",
      "audio": "https://example.com/audio.mp3"
    }
  }'

Response

Response is a JSON object with the following structure

Field

Type

Description

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

Field

Type

Description

string

unique message id

event

string

one of SENT DELIVERED READ

phone

string

Phone no. in E164 Format starting + with country code and phone number without any space or other chars

name

string

Name of user set in QuickReply

string

Email of user if set in QuickReply

messageBy

string

one of AUTOMATION or AGENT

agentId

string

When messageBy is AGENT, it contains agent who sent message

automationBy

string

When messageBy is AUTOMATION, it contains what automation triggered this message. It will be one of BROADCAST CAMPAIGN JOURNEY API_TEMPLATE CHAT_BOT

broadcastId

string

if automationBy is BROADCAST it contains broadcast id

campaignId

string

if automationBy is CAMPAIGN it contains campaign id

journeyId

string

if automationBy is JOURNEY it contains journey id

templateId

string

if it is template message, it contains template id

Important Notes

If you want your system to generate responses to incoming messages, you can ignore message events for messages not sent by you via API.
If you are using GenAI/LLM to generate responses, you might need message history that you have to maintain on your own.

How to Configure Webhooks?

To configure Webhooks, Send the URL you would like to configure to help@quickreply.ai and our support team will assist you.

PreviousSend Template API NextExternal CRM Integration & Contact Syncing

Last updated 2 days ago