Connectly Documentation
  • 👋Welcome to Connectly.ai
  • 🚀Quick Start
    • Prerequisites
    • Authentication
    • Send WhatsApp template message
    • Send WhatsApp session message
  • 📣Campaigns
    • Campaign Sendout
      • Send Campaigns
  • 🤖Sofia AI
    • How to use Sofia AI?
    • Sofia AI API
      • Reference
        • Core Concepts
        • sales_assistant_v2/invoke/v1
  • 📱Message API
    • Message Service API
      • MessageService
        • Send template message
        • Send session message
      • Error codes
    • Webhook API
      • WebhookService
        • Create a webhook registration by event topic
        • Update an existing webhook registration by event topic
        • Get webhook registrations for business
        • Delete a webhook registration for business
      • Webhook Payload
        • Delivery Status Error Codes
        • Payload Media Types
  • 🤖Business Management
    • Business Management API
      • Template Management
        • Create a template
        • Get templates
      • Quality Signals
  • 📱Integrations
    • Integrations
      • WebEngage Integration
      • Message your customers on Zendesk through Connectly
      • Message your customer on Intercom through Connectly
    • [Alpha] Moengage
      • MessageService
        • Send Campaign via API
  • 📊Analytics
    • Analytics
      • [Alpha] Campaign report
      • Reports API
        • Webhooks configuration
  • 👀FAQ
  • Migrating WhatsApp Accounts
  • How to use time delay?
Powered by GitBook
On this page
  • Messages
  • Delivery Status
  1. Message API

Webhook API

Currently only WhatsApp webhook events are supported

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": "+16315555500",
    "channelType": "whatsapp",
    "name": "Vasi from Connectly"
  },
  "recipient": {
    "id": "+16044441234",
    "channelType": "whatsapp",
    "name": "connectlyai"
  },
  "message": {
    "text": "TEST 11"
  },
  "attachments": [],
  "location": null
}

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 gives 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>"
}
  1. You will start receiving the delivery notification events like this:

JSON

{
  "topic": "delivery_status",
  "timestamp": "1641513098",
  "sender": {
    "id": "+16044441234",
    "channelType": "whatsapp",
    "name": "connectlyai"
  },
  "recipient": {
    "id": "+16315555500",
    "channelType": "whatsapp",
    "name": "Vasi from Connectly"
  },
  "statusUpdate": {
    "id": "01FRRWW2ZAHD9GJ1SWY4VF2GBD",
    "status": "delivered",
    "error": null,
    "metadata": {
      "campaignName": "connectly_test_campaign"
    }
  }
}

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": "+16044441234",
    "channelType": "whatsapp",
    "name": "connectlyai"
  },
  "recipient": {
    "id": "+16315555500",
    "channelType": "whatsapp",
    "name": "Vasi from Connectly"
  },
  "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

PreviousError codesNextWebhookService

Last updated 11 months ago

📱