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

Body

Payload Object

Preview Object

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

Reply Preview Object

URL Preview Object

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

Body

payload

  • 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

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

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