Prerequisites

This page will help you get started with our API

Message Service

Message Service allows one to send messages to a target channel(SMS, WhatsApp, etc). There are two types of messages that we are currently supporting: text and template.

WARNING if you have not initiated the conversation first you CAN NOT send a message on WhatsApp. In this case, you MUST use the template message to first initiate conversation. If you are using your personal number to test try sending a message to your Connectly WhatsApp business number first and then send a regular text WhatsApp message.

Below is a curl example to send a text message to a WhatsApp number:

cURL

curl --request POST \
     --url https://api.connectly.ai/v1/businesses/<business_id>/send/messages \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'X-API-Key: <YOUR_KEY_HERE>' \
     --data '
{
     "recipient": {
          "channelType": "whatsapp",
          "id": "[phone]"
     },
     "message": {
          "text": "hello!"
     }
}'

Here's another example to send a template message to a given WhatsApp number.

cURL

curl --request POST \
     --url https://api.connectly.ai/v1/businesses/<business_id>/send/whatsapp_templated_messages \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'X-API-Key: <YOUR_KEY_HERE>' \
     --data '
{
     "parameters": [
          {
               "name": "var1",
               "value": "value1"
          },
          {
               "name": "var2",
               "value": "value2"
          }
     ],
     "number": "<WA_NUumber>",
     "templateName": "<Template_name>"
}'

Webhook

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:

JSON

// 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

JavaScript

const crypto = require("crypto");

app.post('/webhooks', function(req, res) {
    const secret = "YOUR_SECRET_VALUE"
    const retrievedSignature = req.get("x-connectly-hmac-sha256")
    const bodyString = Buffer.from(req.rawBody, 'utf8')

    hash = crypto.createHmac("sha256", secret).update(bodyString).digest("base64");
    if (hash === retrievedSignature) {
    		res.send(200);
    }
		res.send(403);
});

JavaScript has express-middleware that can do this for you: https://github.com/neeler/express-verify-hmac-signature

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