Incoming Messages

In this section, you will be acquainted with receiving messages / inbound flow over WhatsApp.
Since WhatsApp is used for 2-way communication (chat), it is important to also implement an Inbound flow. You may configure webhook URLs for receiving the incoming message or delivery reports of the outgoing message. Unifonic's conversation platform allows you to configure multiple webhook URLs .

📘

Webhooks are necessary if...

you are embedding Unifonic Conversation APIs with third party chatbot/agent console. Without webhooks, you will not get your incoming messages in real time.

Configuring Webhook URLs

  1. Navigate to the Channels > WhatsApp.

  1. Click the Edit button, and navigate to the WEBHOOK tab.

  1. Click ADD NEW to paste the webhook URL on which the user would like to receive the incoming webhook responses for received messages

Sample: Received Message from a Quick Reply Button

{
  "messageId": "4ac6890b-1756-4d6d-XXXXXXXXXXXXXXX",
  "eventId": "23d47231-XXXX-4371-bf3c-XXXXXXXXX",
  "eventType": "message.received",
  "applicationId": "5dXXXXee-2da0-XXXX-82c1-7245XXXXXXXXX",
  "parentMessageId": "278XXXX-663b-4bXX-97dc-295XXXXXd9XX",
  "conversationId": "dcXXcf75-XXXX-4701-9cXb-3ee0XXXXXXX6",
  "sender": {
    "channel": "whatsapp",
    "contact": "+966XXXXXXXX",
    "name": "XXXXXX"
  },
  "content": {
    "text": "section title1",
    "type": "option",
    "attachments": [
      {
        "type": "option",
        "option": {
          "text": "See more",
          "value": "id1"
        }
      }
    ]
  },
  "timestamp": "2023-05-02T11:33:20.000Z",
  "receivedAt": "2023-05-02T11:33:21.092Z"
}

Sample: Received Message with Free Text

{
  "messageId": "4ac6890b-1756-4d6d-XXXXXXXXXXXXXXX",
  "eventId": "23d47231-XXXX-4371-bf3c-XXXXXXXXX",
  "eventType": "message.received",
  "applicationId": "5dXXXXee-2da0-XXXX-82c1-7245XXXXXXXXX",
  "parentMessageId": "278XXXX-663b-4bXX-97dc-295XXXXXd9XX",
  "conversationId": "dcXXcf75-XXXX-4701-9cXb-3ee0XXXXXXX6",
  "sender": {
    "channel": "whatsapp",
    "contact": "+966XXXXXXXX",
    "name": "XXXXXX"
  },
  "content": {
    "text": "Hello",
    "type": "text"
  },
  "timestamp": "2023-05-02T11:36:48.000Z",
  "receivedAt": "2023-05-02T11:36:48.768Z"
}

Sample: Received Message with Image

{
  "messageId": "4ac6890b-1756-4d6d-XXXXXXXXXXXXXXX",
  "eventId": "23d47231-XXXX-4371-bf3c-XXXXXXXXX",
  "eventType": "message.received",
  "applicationId": "5dXXXXee-2da0-XXXX-82c1-7245XXXXXXXXX",
  "parentMessageId": "278XXXX-663b-4bXX-97dc-295XXXXXd9XX",
  "conversationId": "dcXXcf75-XXXX-4701-9cXb-3ee0XXXXXXX6",
  "sender": {
    "channel": "whatsapp",
    "contact": "+966XXXXXXXX",
    "name": "XXXXXX"
  },
  "content": {
    "type": "image",
    "text": null, //user's captions
    "attachments": [
      {
        "type": "image",
        "url": "https://whatsapp.integration-media.dev.unifonic.com/sdsdsdsd-1823-49124-7351-e45123g65a85f47b-4f52-5db4-5beb53db237d.jpg"
      }
    ]
  },
  "timestamp": "2023-05-02T11:36:48.000Z",
  "receivedAt": "2023-05-02T11:36:48.768Z"
}

Sample: Received Message with Document

{
  "messageId": "4ac6890b-1756-4d6d-XXXXXXXXXXXXXXX",
  "eventId": "23d47231-XXXX-4371-bf3c-XXXXXXXXX",
  "eventType": "message.received",
  "applicationId": "5dXXXXee-2da0-XXXX-82c1-7245XXXXXXXXX",
  "parentMessageId": "278XXXX-663b-4bXX-97dc-295XXXXXd9XX",
  "conversationId": "dcXXcf75-XXXX-4701-9cXb-3ee0XXXXXXX6",
  "sender": {
    "channel": "whatsapp",
    "contact": "+966XXXXXXXX",
    "name": "XXXXXX"
  },
  "content": {
    "text": "Ready CompleteCare (English)",
    "type": "file",
    "attachments": [
      {
        "type": "file",
        "url": "https://whatsapp.integration-media.dev.unifonic.com/39494e4f-5005-4924-8781-e45169beb65d/5df2d54d-3d47-49b9-bd2c-2579c35859e5.pdf"
      }
    ]
  },
  "timestamp": "2023-05-02T11:36:48.000Z",
  "receivedAt": "2023-05-02T11:36:48.768Z"

📘

File extension provided

In order for customers to download files that are applicable, we have provided the file extension in the URL

Sample: Received Message with Audio Note/File

{
  "messageId": "4ac6890b-1756-4d6d-XXXXXXXXXXXXXXX",
  "eventId": "23d47231-XXXX-4371-bf3c-XXXXXXXXX",
  "eventType": "message.received",
  "applicationId": "5dXXXXee-2da0-XXXX-82c1-7245XXXXXXXXX",
  "parentMessageId": "278XXXX-663b-4bXX-97dc-295XXXXXd9XX",
  "conversationId": "dcXXcf75-XXXX-4701-9cXb-3ee0XXXXXXX6",
  "sender": {
    "channel": "whatsapp",
    "contact": "+966XXXXXXXX",
    "name": "XXXXXX"
  },
  "content": {
    "text": null,
    "type": "audio",
    "attachments": [
      {
        "type": "audio",
        "url": "https://whatsapp.integration-media.dev.unifonic.com/39sjmnwe4f-5345-4344-8781-ejddxfl9bd/68790-a543-5e7c-b312-ec7de38f34c4.oga"
      }
    ]
  }
  },
  "timestamp": "2023-05-02T11:36:48.000Z",
  "receivedAt": "2023-05-02T11:36:48.768Z"
}

Sample: Received Message with Location

{
  "messageId": "fe355544-9f50-4cc6-a334-6c2e1d7babb4",
  "eventId": "ee6576be-c2f8-4477-80d5-1899eafd09b3",
  "eventType": "message.received",
  "applicationId": "39494e4f-5005-4924-8781-e45169beb65d",
  "parentMessageId": null,
  "conversationId": "fbee2632-1df7-4917-bef8-33050a5ace3e",
  "sender": {
    "channel": "whatsapp",
    "contact": "+966XXXXXXXX",
    "name": "XXXXXXX"
  },
  "content": {
    "text": null,
    "type": "location",
    "attachments": [
      {
        "type": "location",
        "url": "https://foursquare.com/v/5194c5c0498edb9cbc1eb5cb",
        "latitude": "25.07537078857422",
        "longitude": "55.13957595825195",
        "address": "Dubai Marina, Dubai, Dubai",
        "name": "Silverene Tower B"
      }
    ]
  },
  "forwarded": false,
  "frequentlyForwarded": false,
  "referenceId": null,
  "timestamp": "2023-06-21T06:58:32.000Z",
  "receivedAt": "2023-06-21T06:58:32.986Z"
}

🚧

Unsupported fields due to shared format

If the user selects to share current location, information like url, address and name would not be available as it is hard for WhatsApp to assume the exact location name of the user.

If the user selects to share a particular building's location, all information would then be available.

Sample: Received Message with Video

{
  "messageId": "fe355544-9f50-4cc6-a334-6c2e1d7babb4",
  "eventId": "ee6576be-c2f8-4477-80d5-1899eafd09b3",
  "eventType": "message.received",
  "applicationId": "39494e4f-5005-4924-8781-e45169beb65d",
  "parentMessageId": null,
  "conversationId": "fbee2632-1df7-4917-bef8-33050a5ace3e",
  "sender": {
    "channel": "whatsapp",
    "contact": "+966XXXXXXXX",
    "name": "XXXXXXX"
  },
  "content": {
    "text": null,
    "type": "video",
    "attachments": [
      {
        "type": "video",
        "url": "https://whatsapp.integration-media.dev.unifonic.com/3944e4f-2835-4124-8781-e4516e5349a545-6be44-4fa0-9d8d-b0f6086ae7e7.mp4"
      }
    ]
  },
  "forwarded": false,
  "frequentlyForwarded": false,
  "referenceId": null,
  "timestamp": "2023-06-21T06:58:32.000Z",
  "receivedAt": "2023-06-21T06:58:32.986Z"
}

Sample: Received Message with Stickers

{
  "messageId": "fe355544-9f50-4cc6-a334-6c2e1d7babb4",
  "eventId": "ee6576be-c2f8-4477-80d5-1899eafd09b3",
  "eventType": "message.received",
  "applicationId": "39494e4f-5005-4924-8781-e45169beb65d",
  "parentMessageId": null,
  "conversationId": "fbee2632-1df7-4917-bef8-33050a5ace3e",
  "sender": {
    "channel": "whatsapp",
    "contact": "+966XXXXXXXX",
    "name": "XXXXXXX"
  },
  "content": {
    "text": null,
    "type": "sticker",
    "attachments": [
      {
        "type": "sticker",
        "sticker": {
          "id": "c8024b8c-91bf-4b25-a223-3427ffdcbb25",
          "mimeType": "image/webp",
          "sha256": "9043423250edba166f371209a65dd8454ca3b969e7a29e2a58c04a3a23f93"
        }
      }
    ]
  },
  "forwarded": false,
  "frequentlyForwarded": false,
  "referenceId": null,
  "timestamp": "2023-06-21T06:58:32.000Z",
  "receivedAt": "2023-06-21T06:58:32.986Z"
}