API Reference

Delivery status webhook

Delivery status events communicate to you the status of the messages that you have sent to your business clients. Message delivery can fail for various reasons. For example, the phone number may not be on WhatsApp, network failures, incorrect message parameters, etc. We currently support the following events in our webhooks:

  • sent: the message has been sent to the customer(but has not yet been delivered)
  • delivered: the message reached the recipient. It has not been read in the mobile/desktop app. The recipient can read the message from the phone notification though but it will not be registered as read by the recipient's WhatsApp mobile/desktop application.
  • read: the message was read by the recipient within the recipient's WhatsApp mobile/desktop application.
  • delivery_failed: the message failed to reach the recipient. You will be provided with the error code, reason, and trace id that give the explanation as to why it failed. Please contact Connectly team with the trace id to get more details for the explanation.

To register:

curl --request POST \
     --url https://api.connectly.ai/v1/businesses/<business_id>/create/webhooks \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'X-API-Key: <YOUR_KEY_HERE>' \
     --data '
{
    "topic":"delivery_status",
    "address":"<YOUR_ENDPOINT>"
}'

You will start receiving the delivery notification events like this:

{
  "topic": "delivery_status",
  "timestamp": "1641513098",
  "sender": {
    "id": "+16044441111",
    "channelType": "whatsapp"
  },
  "recipient": {
    "id": "+16044551234",
    "channelType": "whatsapp"
  },
  "statusUpdate": {
    "id": "01FRRWW2ZAHD9GJ1SWY4VF2GBD",
    "status": "delivered",
    "error": null
  }
}

Whenever you create a message through the API you will receive back the response created message ID:

{"id": "01FRRVK645V350357FGV2Y1B16"}

When you receive the delivery notification events for the id in the "statusUpdate": object will match the one in the response of the created message ID. You can tie them this way.

In case of errors the delivery status events look like this:

{
  "topic": "delivery_status",
  "timestamp": "1641512856",
  "sender": {
    "id": "+16044441111",
    "channelType": "whatsapp"
  },
  "recipient": {
    "id": "+60445551234",
    "channelType": "whatsapp"
  },
  "statusUpdate": {
    "id": "01FRRWMSAMKNFZAMBPQ65CA7DD",
    "status": "delivery_failed",
    "error": {
      "message": "Message template inputs invalid",
      "type": "ERROR_TYPE_INVALID_REQUEST",
      "code": "ERROR_CODE_MESSAGE_TEMPLATE_INPUT_INVALID",
      "userTitle": "Message template inputs invalid",
      "userMessage": "Pass along the connectly trace id 'cnct_trace_id' to the team for more information.",
      "cntTraceId": "10827968052975079261",
      "details": {
        
      }
    }
  }
}

This should help when you send the WhatsApp template messages to understand whether they reached the final destination or not. You send WhatsApp templated message, you get back the message ID, you store it in your system and get back the delivery status event with that message ID saying if it was sent/delivered/delivery_failed/read.