Webhooks¶
- From one of popular mailing service SendGrid’s blog, they explain the term webhook as following:
- A webhook is an API concept that’s growing in popularity. As more and more of what we do on the web can be described by events, webhooks are becoming even more applicable. They’re incredibly useful and a resource-light way to implement event reactions.
So we will send HTTP requests to inform you about available updates which are specified as follows:
| Event | When will be send |
|---|---|
| conversation.created | When a conversation is created |
| message.created | When a conversation replied by customer or agent |
| message.state_changed | When a message state is changed |
| conversation.auto_assign | To specify to be assigned which agent |
| conversation.assigned | When a conversation assigned to an agent |
| conversation.archived | When a conversation archived, sends all messages with all attachments |
| conversation.type_changed | When a conversation type changed, sends all messages with all attachments |
| conversation.custom_fields_updated | When a conversation custom fields changed |
| customer.updated | When agent edits a customer |
| feedback.received | When a feedback received |
| agent.status_changed | When an agent status changed |
| conversation.group_changed | When a user group changed in conversation |
Warning
You must give a response to requests with a 2xx HTTP status code. We will keep sending requests 30 times until you give a successful response. If you do not reply, the response message is deleted.
Note
UTM, and/or language like metadata will be included in data information on conversations and messages.
Verifying webhook requests¶
We will sign webhook requests that we sending with HMAC-SHA256 algorithm.
For PHP, you can use native hash_hmac function. You can see below the code snippets written in other languages.
Python¶
import base64
import hashlib
import hmac
def make_digest(data, key):
key = bytes(key, 'UTF-8')
data = bytes(data, 'UTF-8')
digester = hmac.new(key, data, hashlib.sha256)
signature1 = digester.digest()
signature2 = base64.b64encode(signature1)
return str(signature2, 'UTF-8')
You should compare X-Connexease-Webhook-Sign header when received a webhook request.
import json
from django.http import HttpResponse
def connexease_webhooks(request):
secret_key = 'awesome-secret-key'
sign = request.META.get('X-Connexease-Webhook-Sign')
channel_uuid = json.loads(request.body).get('channel').get('uuid')
generated_digest = make_digest(channel_uuid, secret_key)
if generated_digest != sign:
return HttpResponse('Webhook-Sign Could Not Verified!')
C#¶
Very simple endpoint for handling connexease webhooks written in .NET Core MVC.
using System;
using System.Text;
using System.Collections.Generic;
using System.Security.Cryptography;
using Microsoft.AspNetCore.Mvc;
using Newtonsoft.Json;
using Newtonsoft.Json.Linq;
namespace WebhookHandler.Controllers
{
[Route("webhook")]
[ApiController]
public class WebhookController : ControllerBase
{
public static string MakeDigest(string data, string key)
{
var keyByte = Encoding.UTF8.GetBytes(key);
var digest = new HMACSHA256(keyByte);
digest.ComputeHash(Encoding.UTF8.GetBytes(data));
return System.Convert.ToBase64String(digest.Hash);
}
[Route("")]
[HttpPost]
public void WebhookHandler(JObject webhook_body)
{
string sign = Request.Headers["X-Connexease-Webhook-Sign"];
JObject channel = (JObject)webhook_body["channel"];
string channel_uuid = (string)channel["uuid"];
string secretKey = "your-awesome-secret-key";
string signGenerated = MakeDigest(channel_uuid, secretKey);
if (sign == signGenerated) {
// Success.
}
else {
// Fail.
}
}
}
}
Available hooks¶
Conversation created¶
When the conversation is started by the customer, the response message is created.
Request:
POST: /webhook/
{
"hook": "conversation.created",
"account": {
"uuid": "2fbcadf6-c91a-4d1f-9ed4-d4ef5f6d1362",
"name": "Acme Ltd"
},
"channel": {
"uuid": "9cbee132-db65-4437-8825-844ca1dcfc1e",
"name": "Live Support",
"backend": "live_chat"
},
"payload": {
"uuid": "e94f00c6-0193-49db-b93b-c8931b56ba16",
"account": "2fbcadf6-c91a-4d1f-9ed4-d4ef5f6d1362",
"channel": "9cbee132-db65-4437-8825-844ca1dcfc1e",
"customer": {
"uuid": "d46fd69a-0584-41d3-8c0a-f90a4435b27b",
"name": "John Doe",
"mail": "[email protected]",
"phone_number": "+90518384443"
},
"type": null,
"custom_fields": {
},
"data": {
"pdf": "PDF URL"
},
"is_archived": false,
"archived_at": "None",
"archived_by": null,
"assigned_at": "None",
"assigned_to": null,
"assigned_group": {
"uuid": "d46fd69a-0584-41d3-8c0a-f90a4435b27b",
"name": "Only US Region"
},
"messages": {
"id": 378,
"conversation_uuid": "e94f00c6-0193-49db-b93b-c8931b56ba16",
"channel_identifier": "172CBFF7C637CEA6913C36E0CA1E9CB7",
"agent": null,
"customer": {
"uuid": "d46fd69a-0584-41d3-8c0a-f90a4435b27b",
"name": "John Doe",
"mail": "[email protected]",
"phone_number": "+90518384443"
},
"type": "text",
"content": "22",
"data": {
"language": "turkish"
},
"media_url": null,
"latitude": null,
"longitude": null
}
}
}
Conversation assigned¶
When a conversation is assigned, all information about that conversation is sent.
Request:
{
"hook": "conversation.assigned",
"account": {
"uuid": "2fbcadf6-c91a-4d1f-9ed4-d4ef5f6d1362",
"name": "Acme Ltd"
},
"channel": {
"uuid": "9cbee132-db65-4437-8825-844ca1dcfc1e",
"name": "Live Support",
"backend": "live_chat"
},
"payload": {
"uuid": "e07c18f3-e1a8-4d41-a362-71a536d0cb21",
"account": "2fbcadf6-c91a-4d1f-9ed4-d4ef5f6d1362",
"channel": "9cbee132-db65-4437-8825-844ca1dcfc1e",
"customer": {
"uuid": "487947db-f7e9-4b31-955a-3987475fe766",
"name": null,
"mail": null,
"phone_number": null,
"crm": null
},
"type": "About Order",
"custom_fields": {
"order_number": {
"value": "C-123456"
},
"return_date": {
"value": "2018-03-27 10:00:19.697269+00:00"
},
"6b7540d2-6b89-4da6-9276-feb6bc647139": {
"value": "Text"
},
"a8f8443c-d972-44bb-82f3-751697b601b3": {
"value": 123456
}
},
"data": {
"utm": {
"utm_source": "google",
"utm_medium": "banner",
},
"pdf": "PDF URL"
},
"is_archived": false,
"archived_at": null,
"archived_by": null,
"assigned_at": "2018-03-26 06:57:18.661949+00:00",
"assigned_to": {
"uuid": "f00b6c2f-0af6-47a2-b4e0-82bf2fa2c8a4",
"first_name": "Agent",
"last_name": "2",
"mail": "[email protected]"
},
"assigned_group": null,
"messages": [
{
"id": 87,
"conversation_uuid": "e07c18f3-e1a8-4d41-a362-71a536d0cb21",
"channel_identifier": "23497864357891298487234079341248",
"agent": null,
"customer": {
"uuid": "487947db-f7e9-4b31-955a-3987475fe766",
"name": null,
"mail": null,
"phone_number": null,
"crm": null
},
"type": "text",
"content": ".",
"data": {
"language": "turkish"
},
"media_url": null,
"latitude": null,
"longitude": null,
"sent_at": "2018-05-23 08:14:55.300273+00:00",
"create_at": "2018-05-23 08:14:55.749446+00:00"
},
{
"id": 321,
"conversation_uuid": "e07c18f3-e1a8-4d41-a362-71a536d0cb21",
"channel_identifier": "789431093889497234897345980342",
"agent": null,
"customer": {
"uuid": "487947db-f7e9-4b31-955a-3987475fe766",
"name": null,
"mail": null,
"phone_number": null,
"crm": null
},
"type": "media",
"content": null,
"data": {
"language": null
},
"media_url": "https://allinone-cdn.tusla.com.tr/33f57b1e-5e16-4df1-b7d8-2949fa8acf9aaX2ORz.jpg",
"latitude": null,
"longitude": null,
"sent_at": "2018-05-23 08:15:55.300273+00:00",
"create_at": "2018-05-23 08:15:55.749446+00:00"
},
{
"id": 332,
"conversation_uuid": "e07c18f3-e1a8-4d41-a362-71a536d0cb21",
"channel_identifier": null,
"agent": {
"uuid": "f00b6c2f-0af6-47a2-b4e0-82bf2fa2c8a4",
"first_name": "Agent",
"last_name": "2",
"mail": "[email protected]"
},
"customer": null,
"type": "location",
"content": null,
"data": {
"language": null
},
"media_url": null,
"latitude": "41.0321733",
"longitude": "28.9858517",
"sent_at": "2018-05-23 08:16:55.300273+00:00",
"create_at": "2018-05-23 08:16:55.749446+00:00"
},
.
.
.
}
}
Conversation archived¶
When a conversation is archived, all information about that conversation is sent.
Request:
{
"hook": "conversation.archived",
"account": {
"uuid": "2fbcadf6-c91a-4d1f-9ed4-d4ef5f6d1362",
"name": "Acme Ltd"
},
"channel": {
"uuid": "9cbee132-db65-4437-8825-844ca1dcfc1e",
"name": "Live Support",
"backend": "live_chat"
},
"payload": {
"uuid": "e07c18f3-e1a8-4d41-a362-71a536d0cb21",
"account": "2fbcadf6-c91a-4d1f-9ed4-d4ef5f6d1362",
"channel": "9cbee132-db65-4437-8825-844ca1dcfc1e",
"customer": {
"uuid": "487947db-f7e9-4b31-955a-3987475fe766",
"name": null,
"mail": null,
"phone_number": null,
"crm": null
},
"type": null,
"custom_fields": {
"order_number": {
"value": "C-123456"
},
"6b7540d2-6b89-4da6-9276-feb6bc647139": {
"value": "Text"
},
"a8f8443c-d972-44bb-82f3-751697b601b3": {
"value": 123456
}
},
"data": {
"utm": {
"utm_source": "google",
"utm_medium": "banner",
},
"pdf": "PDF URL"
},
"is_archived": true,
"archived_at": "2018-03-27 10:00:19.697269+00:00",
"archived_by": {
"uuid": "f00b6c2f-0af6-47a2-b4e0-82bf2fa2c8a4",
"first_name": "",
"last_name": "",
"mail": "[email protected]"
},
"assigned_at": "2018-03-26 06:57:18.661949+00:00",
"assigned_to": {
"uuid": "f00b6c2f-0af6-47a2-b4e0-82bf2fa2c8a4",
"first_name": "",
"last_name": "",
"mail": "[email protected]"
},
"assigned_group": null,
"messages": [
{
"id": 87,
"conversation_uuid": "e07c18f3-e1a8-4d41-a362-71a536d0cb21",
"channel_identifier": "23497864357891298487234079341248",
"agent": null,
"customer": {
"uuid": "487947db-f7e9-4b31-955a-3987475fe766",
"name": null,
"mail": null,
"phone_number": null,
"crm": null
},
"type": "text",
"content": ".",
"data": {
"language": "turkish"
},
"media_url": null,
"latitude": null,
"longitude": null,
"sent_at": "2018-05-23 08:14:55.300273+00:00",
"create_at": "2018-05-23 08:14:55.749446+00:00"
},
{
"id": 321,
"conversation_uuid": "e07c18f3-e1a8-4d41-a362-71a536d0cb21",
"channel_identifier": "789431093889497234897345980342",
"agent": null,
"customer": {
"uuid": "487947db-f7e9-4b31-955a-3987475fe766",
"name": null,
"mail": null,
"phone_number": null,
"crm": null
},
"type": "media",
"content": null,
"data": {
"language": null
},
"media_url": "https://allinone-cdn.tusla.com.tr/33f57b1e-5e16-4df1-b7d8-2949fa8acf9aaX2ORz.jpg",
"latitude": null,
"longitude": null,
"sent_at": "2018-05-23 08:15:55.300273+00:00",
"create_at": "2018-05-23 08:15:55.749446+00:00"
},
{
"id": 332,
"conversation_uuid": "e07c18f3-e1a8-4d41-a362-71a536d0cb21",
"channel_identifier": null,
"agent": {
"uuid": "f00b6c2f-0af6-47a2-b4e0-82bf2fa2c8a4",
"first_name": "",
"last_name": "",
"mail": "[email protected]"
},
"customer": null,
"type": "location",
"content": null,
"data": {
"language": null
},
"media_url": null,
"latitude": "41.0321733",
"longitude": "28.9858517",
"sent_at": "2018-05-23 08:16:55.300273+00:00",
"create_at": "2018-05-23 08:16:55.749446+00:00"
},
.
.
.
}
}
Conversation type changed¶
When a conversation is type changed, all information about that conversation is sent.
Request:
{
"hook": "conversation.type_changed",
"account": {
"uuid": "2fbcadf6-c91a-4d1f-9ed4-d4ef5f6d1362",
"name": "Acme Ltd"
},
"channel": {
"uuid": "9cbee132-db65-4437-8825-844ca1dcfc1e",
"name": "Live Support",
"backend": "live_chat"
},
"payload": {
"uuid": "e07c18f3-e1a8-4d41-a362-71a536d0cb21",
"account": "2fbcadf6-c91a-4d1f-9ed4-d4ef5f6d1362",
"channel": "9cbee132-db65-4437-8825-844ca1dcfc1e",
"customer": {
"uuid": "487947db-f7e9-4b31-955a-3987475fe766",
"name": null,
"mail": null,
"phone_number": null,
"crm": null
},
"type": "About Order",
"custom_fields": {
"order_number": {
"value": "C-123456"
},
"return_date": {
"value": "2018-03-27 10:00:19.697269+00:00"
},
"6b7540d2-6b89-4da6-9276-feb6bc647139": {
"value": "Text"
},
"a8f8443c-d972-44bb-82f3-751697b601b3": {
"value": 123456
}
},
"data": {
"utm": {
"utm_source": "google",
"utm_medium": "banner",
},
"pdf": "PDF URL"
},
"is_archived": false,
"archived_at": null,
"archived_by": null,
"assigned_at": "2018-03-26 06:57:18.661949+00:00",
"assigned_to": {
"uuid": "f00b6c2f-0af6-47a2-b4e0-82bf2fa2c8a4",
"first_name": "",
"last_name": "",
"mail": "[email protected]"
},
"assigned_group": null,
"messages": [
{
"id": 87,
"conversation_uuid": "e07c18f3-e1a8-4d41-a362-71a536d0cb21",
"channel_identifier": "23497864357891298487234079341248",
"agent": null,
"customer": {
"uuid": "487947db-f7e9-4b31-955a-3987475fe766",
"name": null,
"mail": null,
"phone_number": null,
"crm": null
},
"type": "text",
"content": ".",
"data": {
"language": "turkish"
},
"media_url": null,
"latitude": null,
"longitude": null,
"sent_at": "2018-05-23 08:14:55.300273+00:00",
"create_at": "2018-05-23 08:14:55.749446+00:00"
},
{
"id": 321,
"conversation_uuid": "e07c18f3-e1a8-4d41-a362-71a536d0cb21",
"channel_identifier": "789431093889497234897345980342",
"agent": null,
"customer": {
"uuid": "487947db-f7e9-4b31-955a-3987475fe766",
"name": null,
"mail": null,
"phone_number": null,
"crm": null
},
"type": "media",
"content": null,
"data": {
"language": null
},
"media_url": "https://allinone-cdn.tusla.com.tr/33f57b1e-5e16-4df1-b7d8-2949fa8acf9aaX2ORz.jpg",
"latitude": null,
"longitude": null,
"sent_at": "2018-05-23 08:15:55.300273+00:00",
"create_at": "2018-05-23 08:15:55.749446+00:00"
},
{
"id": 332,
"conversation_uuid": "e07c18f3-e1a8-4d41-a362-71a536d0cb21",
"channel_identifier": null,
"agent": {
"uuid": "f00b6c2f-0af6-47a2-b4e0-82bf2fa2c8a4",
"first_name": "",
"last_name": "",
"mail": "[email protected]"
},
"customer": null,
"type": "location",
"content": null,
"data": {
"language": null
},
"media_url": null,
"latitude": "41.0321733",
"longitude": "28.9858517",
"sent_at": "2018-05-23 08:16:55.300273+00:00",
"create_at": "2018-05-23 08:16:55.749446+00:00"
},
.
.
.
}
}
Conversation custom fields changed¶
When a conversation custom fields changed, sends all messages with all attachments
Request:
{
"hook": "conversation.custom_fields_updated",
"account": {
"uuid": "2fbcadf6-c91a-4d1f-9ed4-d4ef5f6d1362",
"name": "Acme Ltd"
},
"channel": {
"uuid": "9cbee132-db65-4437-8825-844ca1dcfc1e",
"name": "Live Support",
"backend": "live_chat"
},
"payload": {
"uuid": "e07c18f3-e1a8-4d41-a362-71a536d0cb21",
"account": "2fbcadf6-c91a-4d1f-9ed4-d4ef5f6d1362",
"channel": "9cbee132-db65-4437-8825-844ca1dcfc1e",
"customer": {
"uuid": "487947db-f7e9-4b31-955a-3987475fe766",
"name": null,
"mail": null,
"phone_number": null,
"crm": null
},
"type": "About Order",
"custom_fields": {
"order_number": {
"value": "C-123456"
},
"return_date": {
"value": "2018-03-27 10:00:19.697269+00:00"
},
"6b7540d2-6b89-4da6-9276-feb6bc647139": {
"value": "Text"
},
"a8f8443c-d972-44bb-82f3-751697b601b3": {
"value": 123456
}
},
"data": {
"utm": {
"utm_source": "google",
"utm_medium": "banner",
},
"pdf": "PDF URL"
},
"is_archived": false,
"archived_at": null,
"archived_by": null,
"assigned_at": "2018-03-26 06:57:18.661949+00:00",
"assigned_to": {
"uuid": "f00b6c2f-0af6-47a2-b4e0-82bf2fa2c8a4",
"first_name": "",
"last_name": "",
"mail": "[email protected]"
},
"assigned_group": null,
"messages": [
{
"id": 87,
"conversation_uuid": "e07c18f3-e1a8-4d41-a362-71a536d0cb21",
"channel_identifier": "23497864357891298487234079341248",
"agent": null,
"customer": {
"uuid": "487947db-f7e9-4b31-955a-3987475fe766",
"name": null,
"mail": null,
"phone_number": null,
"crm": null
},
"type": "text",
"content": ".",
"data": {
"language": "turkish"
},
"media_url": null,
"latitude": null,
"longitude": null,
"sent_at": "2018-05-23 08:14:55.300273+00:00",
"create_at": "2018-05-23 08:14:55.749446+00:00"
},
{
"id": 321,
"conversation_uuid": "e07c18f3-e1a8-4d41-a362-71a536d0cb21",
"channel_identifier": "789431093889497234897345980342",
"agent": null,
"customer": {
"uuid": "487947db-f7e9-4b31-955a-3987475fe766",
"name": null,
"mail": null,
"phone_number": null,
"crm": null
},
"type": "media",
"content": null,
"data": {
"language": null
},
"media_url": "https://allinone-cdn.tusla.com.tr/33f57b1e-5e16-4df1-b7d8-2949fa8acf9aaX2ORz.jpg",
"latitude": null,
"longitude": null,
"sent_at": "2018-05-23 08:15:55.300273+00:00",
"create_at": "2018-05-23 08:15:55.749446+00:00"
},
.
.
.
],
"custom_fields": {
"order_number": {
"value": "12345"
},
"order_date": {
"value": "2020-08-17 10:22"
},
"6b7540d2-6b89-4da6-9276-feb6bc647139": {
"value": "Text"
},
"a8f8443c-d972-44bb-82f3-751697b601b3": {
"value": 123456
}
}
}
}
Conversation user group changed¶
When a conversation user group changed, all information about that conversation is sent.
Request:
{
"hook": "conversation.group_changed",
"account": {
"uuid": "2fbcadf6-c91a-4d1f-9ed4-d4ef5f6d1362",
"name": "Acme Ltd"
},
"channel": {
"uuid": "9cbee132-db65-4437-8825-844ca1dcfc1e",
"name": "Live Support",
"backend": "live_chat"
},
"payload": {
"uuid": "e07c18f3-e1a8-4d41-a362-71a536d0cb21",
"account": "2fbcadf6-c91a-4d1f-9ed4-d4ef5f6d1362",
"channel": "9cbee132-db65-4437-8825-844ca1dcfc1e",
"customer": {
"uuid": "487947db-f7e9-4b31-955a-3987475fe766",
"name": null,
"mail": null,
"phone_number": null,
"crm": null
},
"type": "About Order",
"custom_fields": {
"order_number": {
"value": "C-123456"
},
"return_date": {
"value": "2018-03-27 10:00:19.697269+00:00"
},
"6b7540d2-6b89-4da6-9276-feb6bc647139": {
"value": "Text"
},
"a8f8443c-d972-44bb-82f3-751697b601b3": {
"value": 123456
}
},
"data": {
"utm": {
"utm_source": "google",
"utm_medium": "banner",
},
"pdf": "PDF URL"
},
"is_archived": false,
"archived_at": null,
"archived_by": null,
"assigned_at": "2018-03-26 06:57:18.661949+00:00",
"assigned_to": {
"uuid": "f00b6c2f-0af6-47a2-b4e0-82bf2fa2c8a4",
"first_name": "",
"last_name": "",
"mail": "[email protected]"
},
'assigned_group': {
'uuid': 'c9a0768d-7c99-4957-ac0f-d8eda9996da2',
'name': 'Everyone'
},
"messages": [
{
"id": 87,
"conversation_uuid": "e07c18f3-e1a8-4d41-a362-71a536d0cb21",
"channel_identifier": "23497864357891298487234079341248",
"agent": null,
"customer": {
"uuid": "487947db-f7e9-4b31-955a-3987475fe766",
"name": null,
"mail": null,
"phone_number": null,
"crm": null
},
"type": "text",
"content": ".",
"data": {
"language": "turkish"
},
"media_url": null,
"latitude": null,
"longitude": null,
"sent_at": "2018-05-23 08:14:55.300273+00:00",
"create_at": "2018-05-23 08:14:55.749446+00:00"
},
{
"id": 321,
"conversation_uuid": "e07c18f3-e1a8-4d41-a362-71a536d0cb21",
"channel_identifier": "789431093889497234897345980342",
"agent": null,
"customer": {
"uuid": "487947db-f7e9-4b31-955a-3987475fe766",
"name": null,
"mail": null,
"phone_number": null,
"crm": null
},
"type": "media",
"content": null,
"data": {
"language": null
},
"media_url": "https://allinone-cdn.tusla.com.tr/33f57b1e-5e16-4df1-b7d8-2949fa8acf9aaX2ORz.jpg",
"latitude": null,
"longitude": null,
"sent_at": "2018-05-23 08:15:55.300273+00:00",
"create_at": "2018-05-23 08:15:55.749446+00:00"
},
{
"id": 332,
"conversation_uuid": "e07c18f3-e1a8-4d41-a362-71a536d0cb21",
"channel_identifier": null,
"agent": {
"uuid": "f00b6c2f-0af6-47a2-b4e0-82bf2fa2c8a4",
"first_name": "",
"last_name": "",
"mail": "[email protected]"
},
"customer": null,
"type": "location",
"content": null,
"data": {
"language": null
},
"media_url": null,
"latitude": "41.0321733",
"longitude": "28.9858517",
"sent_at": "2018-05-23 08:16:55.300273+00:00",
"create_at": "2018-05-23 08:16:55.749446+00:00"
},
.
.
.
}
}
Message create¶
When a conversation replied by a customer or an agent, information about that message is sent.
Request:
{
"hook": "message.created",
"account": {
"uuid": "2fbcadf6-c91a-4d1f-9ed4-d4ef5f6d1362",
"name": "Acme Ltd"
},
"channel": {
"uuid": "9cbee132-db65-4437-8825-844ca1dcfc1e",
"name": "Live Support",
"backend": "live_chat"
},
"payload": {
"id": 377,
"channel_identifier": "172CBFF7C637CEA6913C36E0CA1E9CB7",
"conversation_uuid": "b09d6c2f-0af6-b4e0-b4e0-3987475fe766",
"agent": {
"uuid": "f00b6c2f-0af6-47a2-b4e0-82bf2fa2c8a4",
"first_name": "",
"last_name": "",
"mail": "[email protected]"
},
"customer": {
"uuid": "487947db-f7e9-4b31-955a-3987475fe766",
"name": null,
"mail": null,
"phone_number": null
},
"type": "media",
"content": null,
"data": {
"language": "turkish",
"interactive": {
"reply_id": "2"
}
},
"media_url": "https://allinone-cdn.tusla.com.tr/badcbb6f-942d-49ad-b50b-0564bcd0f157aX2ORz.jpg",
"latitude": null,
"longitude": null,
"sent_at": "2018-05-23 08:14:55.300273+00:00",
"create_at": "2018-05-23 08:14:55.749446+00:00"
}
}
Note
If the message came from interactive reply buttons or chosen list options, the interactive object with reply_id property shown in the message data property
Example
"data": {
"language": "turkish",
"interactive": {
"reply_id": "2"
}
}
Message state changed¶
When a message state is changed, information about that message is sent.
Request:
{
"hook": "message.state_changed",
"account": {
"uuid": "4eed5ccb-fa39-4d47-89e7-42a121e89b68",
"name": "Acme Ltd"
},
"channel": {
"uuid": "5d890115-2f40-46be-b852-2669e74396ef",
"name": "WA-Dialog360",
"backend": "360_dialog"
},
"payload": {
"id": 187,
"channel_identifier": "gBEGkFNXYEgpAgkB1ZCh29XhEG0",
"conversation_uuid": "f6e5b656-a4e8-41c6-b9ef-63b9474915ae",
"state": "failed | delivered | deleted",
"agent": {
"uuid": "b3058476-6629-441b-8ffb-9974cb5f245f",
"first_name": "",
"last_name": "",
"mail": "[email protected]"
},
"customer": {
"uuid": "9b686ee8-324b-4dae-8c1f-1f8d2cd3f08b",
"name": null,
"mail": null,
"phone_number": "+901231231231",
"crm": null
},
"sent_at": "2021-12-09 08:54:31.322826+00:00",
"create_at": "2021-12-09 08:54:31.337290+00:00"
}
}
Customer updated¶
Information about the related customer will be sent when an agent updates a customer’s info.
Request:
{
"hook": "customer.updated",
"account": {
"uuid": "2fbcadf6-c91a-4d1f-9ed0-d4efsf6d5362",
"name": "Acme Ltd"
},
"channel": {
"uuid": "9cbee452-db65-4437-8825-844ca1dcfc1e",
"name": "Supported",
"backend": "whatsapp"
},
"payload": {
"uuid": "d8f32499-1673-456a-9ae1-0e9fcaea3999",
"name": "Mike",
"mail": null,
"phone_number": "+905211341620",
"crm": null
}
}
Receiving Feedback¶
When a customer makes feedback, information about that feedback is sent.
Request:
{
"hook": "feedback.received",
"account": {
"uuid": "2fbcadf6-c91a-4d1f-9ed0-d4efsf6d5362",
"name": "Acme Ltd"
},
"channel": {
"uuid": "9cbee452-db65-4437-8825-844ca1dcfc1e",
"name": "Supported",
"backend": "whatsapp"
},
"payload": {
"uuid": "6e0e1aec-5ebf-4284-b2b3-856b96c8678a",
"account": "2fbcadf6-c91a-4d1f-9ed0-d4efsf6d5362",
"customer": {
"uuid": "c658cf92-f4ff-4a33-b9da-a6c6d7db75cb",
"name": "Neil Lee",
"mail": null,
"phone_number": "+905404011993",
"crm": null
},
"conversation": "e84f4ce7-1d63-45f0-9d0c-17d6524159c0",
"satisfaction": 4,
"message": "Thanks......",
"type": "emoji"
}
}
Agent status changed¶
When an agent status changed, information about that status change is sent.
Request:
{
"hook": "agent.status_changed",
"account": {
"uuid": "2fbcadf6-c91a-4d1f-9ed0-d4efsf6d5362",
"name": "Acme Ltd"
},
"payload": {
"uuid": "b3058476-6629-441b-8ffb-9974cb5f245f",
"first_name": "",
"last_name": "",
"mail": "[email protected]"
"status": "AVAILABLE | BREAK_TIME | DO_NOT_ASSIGN_ME"
}
}
Webhook response model¶
We offer to you the opportunity to respond back to our webhook requests.
You are free to send messages to your customers, archive a conversation, assign conversations to agents and so on.
We expect 200 status code and application/json type response from you to handle your message. You can build your json response body as in the form of below examples.
Note
If you provide an authentication key to us, we can attach it in the request.
Note
Within webhook response model you can smoothly combine different events in one particular request.
Sending messages¶
{
"events": [
{
"hook": "message.create",
"messages": [
{
"type": "text",
"content": "Hi! Welcome to Connexease. This is an auto message. Bla bla...",
},
{
"type": "location",
"content": "You can find many other products in sale at our outlet shop:",
"lat": 12.345678,
"lng": 12.345678,
},
{
"type": "image",
"content": "and this is a media message",
"url": "https://loremflickr.com/320/240",
}
]
}
]
}
Archiving¶
{
"events": [
{
"hook": "conversation.archive"
}
]
}
Assigning¶
{
"events": [
{
"hook": "conversation.assign",
"agent": {
"email": "[email protected]"
}
}
]
}
Setting Conversation Type¶
If you want to set the sub-conversation type, the sub-conversation type must be in the sub key, and the sub-conversation type must be the main conversation type in the name key. You can set the sub key null for the main conversation type.
{
"events": [
{
"hook": "conversation.type",
"type": {
"name": "About Order",
"sub": "Status" | null
}
}
]
}
Customer Update¶
For specific reasons you might want to update your customer’s name, e.g setting a ticket number as customer name.
{
"events": [
{
"hook": "customer.update",
"customer": {
"name": "John Doe - A23F0004C"
}
}
]
}
Updating Custom Fields¶
Warning
Use the identifier of the custom field.
{
"events": [
{
"hook": "conversation.custom_fields_update",
"custom_fields": {
"order_number": {
"value": "12345"
},
"order_date": {
"value": "2020-08-17 10:22"
},
"6b7540d2-6b89-4da6-9276-feb6bc647139": {
"value": "Text"
},
"a8f8443c-d972-44bb-82f3-751697b601b3": {
"value": 123456
}
}
}
]
}