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 --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": "+15555555555"
},
"message": {
"text": "hello!"
}
}'
Here's another example to send a template message to a given WhatsApp number.
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 --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:
// 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"
},
"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:
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
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.