Working with Webhooks

Messages

Connectly supports sending webhook events to your endpoint. Currently, only WhatsApp messages are supported.
Before receiving webhook events you need to register your endpoint:

cURL

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":"messages",
    "address":"https://example.com/webhook"
}]

The payload example:

cURL

// Headers:
{
  "content-length": "154",
  "x-connectly-hmac-sha256": "OS/QJB97O/sOj3Ugh4vUJ32EE2++vWq9o51ajIJZwuo=",
  "user-agent": "go-resty/2.6.0 (https://github.com/go-resty/resty)",
  "content-type": "text/plain; charset=utf-8",
  "accept-encoding": "gzip"
}
// Body
{
  "timestamp": "1639083206",
  "sender": {
    "id": "[phone]",
    "channelType": "whatsapp"
  },
  "recipient": {
    "id": "123456123",
    "channelType": "whatsapp"
  },
  "message": {
    "text": "TEST 11"
  }
}

The webhook request header contains HMAC Sha256 to verify that the event comes from Connectly. The HMAC can be found in x-connectly-hmac-sha256. To verify the HMAC:

Go

secret := "YOUR_SECRET_VALUE"	
data := string(webhookEventBody)
hash := hmac.New(sha256.New, []byte(secret))
_, err := hash.Write(data)
if err != nil {
	return "", err
}
isValid := webhookEventHMAC == base64.StdEncoding.EncodeToString(hash.Sum(nil)), nil

To acknowledge delivery on your end your endpoint needs to reply with 200 response.

Delivery Status

Delivery status events communicate to you the status of the messages that you have sent to your business clients.

Because WhatsApp works not only on the devices that are connected to the internet but on landline phone networks as well there are many cases when the message can fail to reach the final destination. For example, the phone number may not be on WhatsApp, network failures, incorrect message parameters all can result in message delivery failure.

Also, you can understand whether your message was read by the recipient or not.

The status that Connectly sends to you are:

1. sent - the message was dispatched to the recipient. It has not been delivered yet.

2. 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.

3. read - the message was read by the recipient within the recipient's WhatsApp mobile/desktop application.

4. 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.

5. Register the endpoint against the delivery_status endpoint:
   https://api.connectly.ai/v1/businesses/<BUSINESS_ID>/create/webhooks with payload:

JSON

{
    "topic":"delivery_status",
    "address":"<YOUR_ENDPOINT>"
}

2. You will start receiving the delivery notification events like this:

JSON

{
  "topic": "delivery_status",
  "timestamp": "1641513098",
  "sender": {
    "id": "[phone]",
    "channelType": "whatsapp"
  },
  "recipient": {
    "id": "[phone]",
    "channelType": "whatsapp"
  },
  "statusUpdate": {
    "id": "01FRRWW2ZAHD9GJ1SWY4VF2GBD",
    "status": "delivered",
    "error": null
  }
}

Whenever you create a message through the API (e.g https://api.dev.connectly.ai/v1/businesses/<BUSINESS_ID>/send/messages) you receive back the response created message ID

JSON

{"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:

JSON

{
  "topic": "delivery_status",
  "timestamp": "1641512856",
  "sender": {
    "id": "[phone]",
    "channelType": "whatsapp"
  },
  "recipient": {
    "id": "[phone]",
    "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 delivered/delivery_failed/read