Documentations

Endpoints

Horizontal Navigation

Getting Stats

`GET /stats`

You can fetch statistics using this endpoint. This endpoint will return channel-based statistics at the top level. You have a chance to get account-based or agent-based statistics by aggregating the same metrics using simple math.

For instance, to get an agent’s account-based FRT value starting at the month, you should aggregate all *.stats.agents.*.frt.wtd.sum values and divide by the sum of *.stats.agents.*.frt.wtd.count values.

Status Codes:

200 OK – no error, stats returned

Example request:

GET /stats HTTP/1.1
Authorization: JWT ZG9udHRyeW1lIQ==
Host: stream.connexease.com
Accept: application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "uuid": "c7617c90-0eef-4c75-b604-bdfbc152437c",
        "name": "WhatsApp Main",
        "stats": {
            "messages": {
                "received": {
                    "today": 43,
                    "yesterday": 5,
                    "wtd": 45,
                    "mtd": 125
                },
                "sent":{
                    "today": 43,
                    "yesterday": 5,
                    "wtd": 45,
                    "mtd": 125
                }
            },
            "customers": {
                "new": {
                    "today": 43,
                    "yesterday": 5,
                    "wtd": 45,
                    "mtd": 125
                },
                "total": {
                    "today": 43,
                    "yesterday": 5,
                    "wtd": 45,
                    "mtd": 125
                }
            },
            "response_times": {
                "frt": {
                    "today": {"count": 21, "sum": 4.2},
                    "yesterday": {"count": 21, "sum": 4.2},
                    "wtd": {"count": 21, "sum": 4.2},
                    "mtd": {"count": 21, "sum": 4.2}
                },
                "art": {
                    "today": {"count": 21, "sum": 4.2},
                    "yesterday": {"count": 21, "sum": 4.2},
                    "wtd": {"count": 21, "sum": 4.2},
                    "mtd": {"count": 21, "sum": 4.2}
                }
            },
            "agents": [
                {
                    "uuid": "80f76892-0678-4175-9f17-ffd1afa2bcf5",
                    "name": "John Doe",
                    "joined": {
                        "today": 43,
                        "yesterday": 5,
                        "wtd": 45,
                        "mtd": 125
                    },
                    "viewed": {
                        "today": 43,
                        "yesterday": 5,
                        "wtd": 45,
                        "mtd": 125
                    },
                    "sent": {
                        "today": 43,
                        "yesterday": 5,
                        "wtd": 45,
                        "mtd": 125
                    },
                    "frt": {
                        "today": {"count": 21, "sum": 4.2},
                        "yesterday": {"count": 21, "sum": 4.2},
                        "wtd": {"count": 21, "sum": 4.2},
                        "mtd": {"count": 21, "sum": 4.2}
                    },
                    "art": {
                        "today": {"count": 21, "sum": 4.2},
                        "yesterday": {"count": 21, "sum": 4.2},
                        "wtd": {"count": 21, "sum": 4.2},
                        "mtd": {"count": 21, "sum": 4.2}
                    }
                }
            ]
        }
    }
]

Getting Reports

`GET /reports/`

Creates your account reports of a specified time period.

Status Codes:

200 OK – no error, Report created
400 Bad Request – validation errors

Example request:

GET /reports/?date_range=last_7&trunc=day&data=messages&group_based=true HTTP/1.1
Authorization: JWT ZG9udHRyeW1lIQ==
Host: api.connexease.com
Accept: application/json

Query Parameters:

date_range (string) – available values are today, yesterday, last_7, last_14, last_30, last_week, last_month, wtd, mtd, ytd
trunc (string) – available values are year, month, week, day, hour
data (string) – available values are messages, conversations, response_times, customers, agents, feedback
group_based (string) – available values are true, false or do not send this keyword

Example successful response without group based:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "conversations": {
        "total": [
            {
                "date": "2018-05-30T00:00:00",
                "total": 2
            },
            {
                "date": "2018-06-01T00:00:00",
                "total": 1
            },
            {
                "date": "2018-06-04T00:00:00",
                "total": 5
            },
            {
                "date": "2018-06-05T00:00:00",
                "total": 1
            }
        ],
        "types": [
            {
                "name": "Öneri",
                "sub": "Fikir",
                "total": 3
            },
            {
                "name": "Şikayet",
                "sub": "",
                "total": 1
            },
            {
                "name": "Operational",
                "sub": "",
                "total": 1
            },
            {
                "name": "Sales",
                "sub": "",
                "total": 1
            },
            {
                "name": null,
                "sub": "",
                "total": 3
            }
        ],
        "language": [
            {
                "lang": "turkish",
                "count": 1
            },
            {
                "lang": "english",
                "count": 2
            }
        ]
    },
    "messages": [
        {
            "date": "2018-05-30T00:00:00",
            "outgoing_messages": 19,
            "incoming_messages": 13,
            "total_messages": 32
        },
        {
            "date": "2018-06-01T00:00:00",
            "outgoing_messages": 0,
            "incoming_messages": 28,
            "total_messages": 28
        },
        {
            "date": "2018-06-03T00:00:00",
            "outgoing_messages": 1,
            "incoming_messages": 0,
            "total_messages": 1
        },
        {
            "date": "2018-06-04T00:00:00",
            "outgoing_messages": 22,
            "incoming_messages": 42,
            "total_messages": 64
        },
        {
            "date": "2018-06-05T00:00:00",
            "outgoing_messages": 3,
            "incoming_messages": 3,
            "total_messages": 6
        }
    ],
    "response_times": [
        {
            "date": "2018-05-30T00:00:00",
            "first_response_time": 45.94,
            "avg_response_time": 24.86
        },
        {
            "date": "2018-06-04T00:00:00",
            "first_response_time": 0.29,
            "avg_response_time": 12.46
        },
        {
            "date": "2018-06-05T00:00:00",
            "first_response_time": 0.32,
            "avg_response_time": 0.32
        }
    ],
    "total_response_times": {
        "first_response_time": 13.34,
        "avg_response_time": 16.61
    },
    "customers": [
        {
            "date": "2018-05-30T00:00:00",
            "new": 1,
            "total": 2
        },
        {
            "date": "2018-06-01T00:00:00",
            "new": 1,
            "total": 2
        },
        {
            "date": "2018-06-04T00:00:00",
            "new": 2,
            "total": 6
        },
        {
            "date": "2018-06-05T00:00:00",
            "new": 1,
            "total": 2
        }
    ],
    "agents": [
        {
            "agent_id": 11,
            "uuid": "ad4170a7-738a-4cd5-b096-8ac5c56558be",
            "user__username": "awesomeagent",
            "user__first_name": "Awesome",
            "user__last_name": "Agent",
            "viewed_conversations": 10,
            "touched_conversations": 3,
            "percent": 30.0,
            "sent_messages": 19,
            "first_response_time": 0.11,
            "avg_response_time": 0.11,
            "spent_time": "13:01:30"
        }
    ],
    "feedback": [
        {
            "date": "2018-05-30T00:00:00",
            "total": 5,
            "great": 2,
            "good": 1,
            "soso": 1,
            "bad": 0,
            "terrible": 1

        },
        {
            "date": "2018-06-04T00:00:00",
            "total": 5,
            "great": 2,
            "good": 1,
            "soso": 1,
            "bad": 0,
            "terrible": 1

        }
    ]
}

Example successful response with group based:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "conversations": {
        "total": [
            {
                "date": "2018-05-30T00:00:00",
                "group": "Everyone",
                "total": 2,
                "archived": 2
            },
            {
                "date": "2018-06-01T00:00:00",
                "group": "Support",
                "total": 1,
                "archived": 2
            },
            {
                "date": "2018-06-04T00:00:00",
                "group": "Support",
                "total": 5,
                "archived": 2
            },
            {
                "date": "2018-06-04T00:00:00",
                "group": "Everyone",
                "total": 5,
                "archived": 3
            },
            {
                "date": "2018-06-05T00:00:00",
                "group": "Order",
                "total": 1,
                "archived": 0
            }
        ],
        "types": [
            {
                "name": "Öneri",
                "sub": "",
                "group": "Everyone",
                "total": 3
            },
            {
                "name": "Şikayet",
                "sub": "",
                "group": "Support",
                "total": 1
            },
            {
                "name": "Operational",
                "sub": "Satış",
                "group": "Everyone",
                "total": 1
            },
            {
                "name": "Sales",
                "sub": "",
                "group": "Everyone",
                "total": 1
            },
            {
                "name": null,
                "sub": "",
                "group": "Support",
                "total": 3
            }
        ],
        "language": [
            {
                "group": "Everyone",
                "lang": "turkish",
                "count": 1
            },
            {
                "group": "Support",
                "lang": "english",
                "count": 2
            }
        ]
    },
    "messages": [
        {
            "date": "2018-05-30T00:00:00",
            "group": "Everyone",
            "outgoing_messages": 19,
            "incoming_messages": 13,
            "total_messages": 32
        },
        {
            "date": "2018-06-01T00:00:00",
            "group": "Support",
            "outgoing_messages": 0,
            "incoming_messages": 28,
            "total_messages": 28
        },
        {
            "date": "2018-06-03T00:00:00",
            "group": "Order",
            "outgoing_messages": 1,
            "incoming_messages": 0,
            "total_messages": 1
        },
        {
            "date": "2018-06-04T00:00:00",
            "group": "Everyone",
            "outgoing_messages": 22,
            "incoming_messages": 42,
            "total_messages": 64
        },
        {
            "date": "2018-06-05T00:00:00",
            "group": "Everyone",
            "outgoing_messages": 3,
            "incoming_messages": 3,
            "total_messages": 6
        }
    ],
    "response_times": [
        {
            "date": "2018-05-30T00:00:00",
            "group": "Everyone",
            "first_response_time": 45.94,
            "avg_response_time": 24.86
        },
        {
            "date": "2018-06-04T00:00:00",
            "group": "Support",
            "first_response_time": 0.29,
            "avg_response_time": 12.46
        },
        {
            "date": "2018-06-05T00:00:00",
            "group": "Everyone",
            "first_response_time": 0.32,
            "avg_response_time": 0.32
        }
    ],
    "total_response_times": [
        {
            "group": "Everyone",
            "first_response_time": 13.34,
            "avg_response_time": 16.61
        },
        {
            "group": "Support",
            "first_response_time": 10.34,
            "avg_response_time": 8.21
        },
    ],
    "customers": [
        {
            "date": "2018-05-30T00:00:00",
            "new": 1,
            "total": 2
        },
        {
            "date": "2018-06-01T00:00:00",
            "new": 1,
            "total": 2
        },
        {
            "date": "2018-06-04T00:00:00",
            "new": 2,
            "total": 6
        },
        {
            "date": "2018-06-05T00:00:00",
            "new": 1,
            "total": 2
        }
    ],
    "agents": [
        {
            "agent_id": 11,
            "uuid": "ad4170a7-738a-4cd5-b096-8ac5c56558be",
            "user__username": "awesomeagent",
            "user__first_name": "Awesome",
            "user__last_name": "Agent",
            "viewed_conversations": 10,
            "touched_conversations": 3,
            "percent": 30.0,
            "sent_messages": 19,
            "first_response_time": 0.11,
            "avg_response_time": 0.11,
            "spent_time": "13:01:30"
        }
    ],
    "feedback": [
        {
            "date": "2018-05-30T00:00:00",
            "total": 5,
            "great": 2,
            "good": 1,
            "soso": 1,
            "bad": 0,
            "terrible": 1

        },
        {
            "date": "2018-06-04T00:00:00",
            "total": 5,
            "great": 2,
            "good": 1,
            "soso": 1,
            "bad": 0,
            "terrible": 1

        }
    ]
}

Send Batch Message

`POST /batch_send_message/`

Send batch messages to selected conversations.

Status Codes:

200 OK – no error, Message sent
400 Bad Request – error, Conversation rate limit

Warning:
You are allowed to send messages to up to 500 conversations at once.

Example request:

POST /batch_send_message/ HTTP/1.1
Authorization: JWT ZG9udHRyeW1lIQ==
Host: api.connexease.com
Accept: application/json

{
    "message": "Lorem ipsum dolor sit amet..",
    "conversations": [
        "b058fe7b-90e3-41f3-b068-76ddbda7deac",
        "cc8f3d99-7c62-4756-967c-280d3f4e4029",
        "6ee80f76-92e6-4570-8f0f-0ae7c38f4dc9",
        "01e2f730-dbb6-4512-b1b4-76044f9ebce6",
        "6fc038ef-0b94-4171-9909-0f0c56ba4c6b"
    ]
}

Example successful response:

HTTP/1.1 200 OK
Content-Type: application/json

Example failed response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "detail": "Too many conversations. You are allowed to send to max 500 conversations."
}

Getting Chat Based Report

`GET /reports/conversations/`

Creates your account’s conversation based reports of a specified time period.

Status Codes:

200 OK – no error, Report created
400 Bad Request – validation errors
403 Forbidden – authority error

Example request:

GET /reports/conversations/?created_at_range=last_7 HTTP/1.1
Authorization: JWT ZG9udHRyeW1lIQ==
Host: api.connexease.com
Accept: application/json

Query Parameters:

created_at_range (string) – If you want to filter conversations by created_at, then use this. One of: today, yesterday, last_7, last_14, last_30, last_week, last_month, wtd, mtd, ytd.
archived_at_range (string) – If you want to filter conversations by archived_at, then use this. One of: today, yesterday, last_7, last_14, last_30, last_week, last_month, wtd, mtd, ytd.

Example successful response:

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "uuid": "c6d0dca5-6731-419f-9361-9942a5921fe1",
        "type": {
            "main_type": "Payment Method",
            "sub_type1": "Paying At The Door",
            "sub_type2": "Cash"
        },
        "group": "Support",
        "language": "turkish",
        "created_at": "2018-07-13T07:23:54.167291Z",
        "is_archived": false,
        "archived_at": null,
        "reponse_times": {
            "first_response_time": 0.01,
            "avg_response_time": 0.01
        },
        "customer": {
            "uuid": "f9737e4f-94af-4a2f-845c-945d4738519b",
            "name": "John Dou",
            "phone_number": "+2025550157",
            "email": null,
            "crm": null
        },
        "messages": {
            "total": 6,
            "incoming": 4,
            "outgoing": 2
        }
    },
    {
        "uuid": "2f66eaa2-452d-4cef-9c8f-5e980bb1f4f7",
        "type": "Support",
        "group": "Everyone",
        "language": "turkish",
        "created_at": "2018-07-13T07:03:08.365089Z",
        "is_archived": true,
        "archived_at": "2018-07-13T07:27:42.262216Z",
        "reponse_times": {
            "first_response_time": 0.73,
            "avg_response_time": 0.73
        },
        "customer": {
            "uuid": "251cebdd-5c78-4139-a239-73a97dfff56e",
            "name": "Derya Deniz",
            "phone_number": "+5725550156",
            "email": null,
            "crm": null
        },
        "messages": {
            "total": 4,
            "incoming": 3,
            "outgoing": 1
        }
    },
    {
        "uuid": "fde74348-a205-40a4-8ed7-6feceb26d459",
        "type": null,
        "group": "Support",
        "language": "turkish",
        "created_at": "2018-07-13T07:22:26.119769Z",
        "is_archived": true,
        "archived_at": "2018-07-13T07:28:24.438854Z",
        "reponse_times": {
            "first_response_time": 0.02,
            "avg_response_time": 0.02
        },
        "customer": {
            "uuid": "9cec5296-be5a-4daa-b737-d6cfab92dfc8",
            "name": "Duygu Kavak",
            "phone_number": "+5725550157",
            "email": null,
            "crm": null
        },
        "messages": {
            "total": 3,
            "incoming": 2,
            "outgoing": 1
        }
    }
]

Example failed response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": "Undefined date range"
}

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "detail": "Invalid Authorization header. No credentials provided."
}

Fetching Messages (Streaming API)

`GET /stream/messages/`

Fetching messages between specified dates.

This service is provided by the streaming service.

Warning: You can receive 100,000 messages at one request. Response comes in NDJSON format.

Status Codes:

200 OK – successful
400 Bad Request – validation errors
401 Unauthorized – auth error
403 Forbidden – unauthorized request

Example request:

GET /stream/messages?created_at__gt=2019-07-16T00:00:00.000001Z&created_at__lt=2019-07-20T23:59:59.000001Z&conversation_customer=true HTTP/1.1
Authorization: JWT ZG9udHRyeW1lIQ==
Host: stream.connexease.com

Query Parameters:

type (string) – text, media, location
sender (string) – agent, customer
channel (string) – Channel UUID.
conversation_uuid (string) – Conversation UUID.
conversation_customer (string) – true, false (default: false)
created_at__gt (string) – ISO 8601 formatted date time string for start date.
created_at__lt (string) – ISO 8601 formatted date time string for end date.

Example successful response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 741244691,
    "created_at": "2019-07-16T21:34:49.107168+00:00",
    "conversation": {
        "uuid": "d0e31490-9c9b-48cb-8c35-310f4570347c",
        "customer": {
            "name": null,
            "uuid": "123123213-051f-4d61-a5fe-121231232131",
            "email": null,
            "phone_number": "+905222222222"
        },
        "is_archived": false
    },
    "channel": {
        "uuid": "d0c83321-c22d-4abd-a9cc-12312312",
        "name": "Channel name",
        "backend": "whatsapp"
    },
    "type": "media",
    "agent": null,
    "customer": {
        "name": null,
        "uuid": "123123213-051f-4d61-a5fe-121231232131",
        "email": null,
        "phone_number": "+905222222222"
    },
    "content": "Hi! Welcome to Connexease. This is an auto message. Bla bla...",
    "data": {
        "url": "...",
        "type": "image",
        "quote": null,
        "language": "turkish",
        "recipient": "905222222222",
        "identifier": "5d2e42f8f3210300012a5128",
        "in_working_hours": true
    }
}
{
    "id": 744244691,
    "created_at": "2019-07-16T21:34:49.107168+00:00",
    "conversation": {
        "uuid": "d0e31490-9c9b-48cb-8c35-310f4570347c",
        "customer": {
            "name": null,
            "uuid": "123123213-051f-4d61-a5fe-121231232131",
            "email": null,
            "phone_number": "+905222222222"
        },
        "is_archived": false
    },
    "channel": {
        "uuid": "d0c83321-c22d-4abd-a9cc-12312312",
        "name": "Channel name",
        "backend": "whatsapp"
    },
    "type": "location",
    "agent": "[email protected]",
    "customer": null,
    "content": "You can find many other products in sale at our outlet shop:",
    "data": {
        "lat": 12.345678,
        "lng": 12.345678
    },
    "group": {
        "name": "The Good, The Bad and The Ugly"
    }
}
{
    "id": 746244691,
    "created_at": "2019-07-16T21:34:49.107168+00:00",
    "conversation": {
        "uuid": "d0e31490-9c9b-48cb-8c35-310f4570347c",
        "customer": {
            "name": null,
            "uuid": "123123213-051f-4d61-a5fe-121231232131",
            "email": null,
            "phone_number": "+905222222222"
        },
        "is_archived": false
    },
    "channel": {
        "uuid": "d0c83321-c22d-4abd-a9cc-12312312",
        "name": "Channel name",
        "backend": "whatsapp"
    },
    "type": "location",
    "agent": "agent1.connexease.com",
    "customer": null,
    "type": "image",
    "content": "and this is a media message",
    "data": {
        "url": "https://loremflickr.com/320/240"
    },
    "group": {
        "name": "The Good, The Bad and The Ugly"
    }
}

Example failed response:

HTTP/1.1 [status code] [status message]
Content-Type: application/json

{
    "error": "Description of the error"
}

Creating Messages

`POST /v2/messages/`

Sending messages to a specified conversation.

Status Codes:

200 OK – successful
400 Bad Request – validation errors
401 Unauthorized – auth error
403 Forbidden – unauthorized request

Example request:

POST /v2/messages/ HTTP/1.1
Authorization: JWT ZG9udHRyeW1lIQ==
Host: api.connexease.com
Accept: application/json

{
    "uuid": "f28a92f9-66cb-444e-9661-45564deebb21",
    "messages": [
        {
            "type": "text",
            "content": "Hi! Welcome to Connexease. This is an auto message. Bla bla..."
        },
        {
            "type": "text",
            "content": "A text message with quoted text",
            "quote": {"quotedContent": "A quoted text"}
        },
        {
            "type": "location",
            "content": "You can find many other products in sale at our outlet shop:",
            "lat": 12.345678,
            "lng": 12.345678
        },
        {
            "type": "location",
            "content": "You can find many other products in sale at our outlet shop with quoted text:",
            "lat": 12.345678,
            "lng": 12.345678,
            "quote": {"quotedContent": "A quoted text"}
        },
        {
            "type": "image",
            "content": "and this is a media message",
            "url": "https://loremflickr.com/320/240",
            "filename": "catPicture"
        },
        {
            "type": "image",
            "content": "and this is a media message with quoted text",
            "url": "https://loremflickr.com/320/240",
            "quote": {"quotedContent": "A quoted text"}
        },
        {
            "type": "video",
            "content": "and this is a media message",
            "url": "https://www.facebook.com/d21c2c4a.mp4",
            "filename": "videoFilename"
        },
        {
            "type": "video",
            "content": "and this is a media message with quoted text",
            "url": "https://www.facebook.com/d21c2c4a.mp4",
            "quote": {"quotedContent": "A quoted text"}
        },
        {
            "type": "document",
            "content": "and this is a media message",
            "url": "https://www.facebook.com/doc.pdf"
            "filename": "optionalFilename.pdf"
        },
        {
            "type": "document",
            "content": "and this is a media message with quoted text",
            "url": "https://www.facebook.com/doc.pdf",
            "quote": {"quotedContent": "A quoted text"}
        },
        {
            "type": "interactive",
            "content": "This is an auto message. Bla bla...",
            "data": {
                "type": "button",
                "header": {
                    "type": "text",
                    "content": "Hello, welcome to Connexease"
                },
                "footer": "We will be happy to assist you.",
                "action": {
                    "items": [
                        {
                            "type": "reply",
                            "content": {
                                "id": "unique ID",
                                "title": "Yes"
                            }
                        },
                        {
                            "type": "reply",
                            "content": {
                                "id": "unique ID",
                                "title": "No"
                            }
                        }
                    ]
                }
            }
        },
        {
            "type": "interactive",
            "content": "This is an auto message. Bla bla...",
            "data": {
                "type": "list",
                "header": {
                    "type": "text",
                    "content": "Hello, welcome to Connexease"
                },
                "footer": "We will be happy to assist you.",
                "action": {
                    "button": "Choose from list",
                    "sections": [
                        {
                            "rows": [
                                {
                                    "id": "1",
                                    "title": "title 1",
                                    "description": "description 1"
                                },
                                {
                                    "id": "2",
                                    "title": "title 4",
                                    "description": "description 4"
                                }
                            ],
                            "title": "row title"
                        }
                    ]
                }
            }
        }
    ]
}

Note:

When you send a location, if you want to send name and address of location, you can use like below. (This only applies to the whatsapp channel.)

Note:

For document messages, The API just supports pdf and msword documents. (pdf, doc, docx, dot, dotx)

Note:

Audio messages are not currently supported by this endpoint.

Example request:

POST /v2/messages/ HTTP/1.1
Authorization: JWT ZG9udHRyeW1lIQ==
Host: api.connexease.com
Accept: application/json

{
    "uuid": "f28a92f9-66cb-444e-9661-45564deebb21",
    "messages": [
        {
            "type": "location",
            "content": "You can find many other products in sale at our outlet shop:",
            "lat": 40.9746468,
            "lng": 29.0778395,
            "address": "Erenköy, Bengi Sk. No: 14/1, 34738 Kadıköy/İstanbul",
            "name": "Connexease"
        },
    ]
}

Note

When you send an interactive message please notice the rules as follow:

The data property can contain:
- type (required): button | list
- header (optional):
  - type (required): The header type you would like to use. Supported values are:
    - text: Used for list, button type.
    - video: Used for button type.
    - image: Used for button type.
    - document: Used for button type.
  - content (required): Related to type can contain data:
    - text: Can contain text for the header. Maximum length is 60 characters.
    - media: If you want to use media, you have to put the media URL into the content. (The protocol and URL of the media to be sent. Use only with HTTP/HTTPS URLs.)

Example:

"header": {
    "type": "image | video | document",
    "content": "media URL"
}

footer (optional): Just text and maximum length are 60 characters.
action (required):
- If type is button you must nest items property:
  - items (required): The array of button objects into items property, you should put button objects here, minimum 1 and maximum 3 objects. Button objects should have the following properties:
    - type (required): Should be reply.
    - content (required): Should have two properties as follows:
      - id (required): Unique id (this id will return when the user clicks on the button).
      - title (required): Button title. It cannot be an empty string and must be unique within the message. Emojis are supported, markdown is not. Maximum length: 20 characters.

Example:

"items": [
    {
        "type": "reply",
        "content": {
            "id": "1",
            "title": "Yes"
        }
    },
    {
        "type": "reply",
        "content": {
            "id": "2",
            "title": "No"
        }
    }
]

If type is list you must nest two objects as follows:
- button (required): Button content. It cannot be an empty string and must be unique within the message. Emojis are supported, markdown is not. (This button is for showing the list)
- sections (required): Array of section objects. There is a minimum of 1 and maximum of 10.
  - section object:
    - title (required if the message has more than one section): Title of the section. Maximum length: 24 characters.
    - rows (required): Contains a list of rows. Each row must have a title (Maximum length: 24 characters) and an ID (Maximum length: 200 characters). You can add a description (Maximum length: 72 characters), but it is optional.

Example:

{
    "title": "row title",
    "rows": [
        {
            "id": "unique id",
            "title": "row title content here",
            "description": "row description"
        }
    ]
}

Example successful response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "detail": "Messages has sent successfully."
}

Example failed response:

HTTP/1.1 401 Bad Request
Content-Type: application/json

{
    "detail": "Your auth key is not valid."
}

Archiving Conversations

`POST /v2/conversations/archive/`

Archiving a specified conversation.

Status Codes:

200 OK – successful
400 Bad Request – validation errors
401 Unauthorized – auth error
403 Forbidden – unauthorized request

Example request:

POST /v2/conversations/archive/ HTTP/1.1
Authorization: JWT ZG9udHRyeW1lIQ==
Host: api.connexease.com
Accept: application/json

{
    "uuid": "f28a92f9-66cb-444e-9661-45564deebb21"
}

Example successful response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "detail": "Conversation has archived successfully."
}

Example failed response:

HTTP/1.1 401 Bad Request
Content-Type: application/json

{
    "detail": "Your auth key is not valid."
}

Assigning to Conversations

`POST /v2/conversations/assign/`

Assigning an agent to a conversation.

Status Codes:

200 OK – successful
400 Bad Request – validation errors
401 Unauthorized – auth error
403 Forbidden – unauthorized request

Example request:

POST /v2/conversations/assign/ HTTP/1.1
Authorization: JWT ZG9udHRyeW1lIQ==
Host: api.connexease.com
Accept: application/json

{
    "uuid": "a28d98f9-66cb-444e-9661-45564deebb21",
    "agent": {
        // Auto assignment
        "auto": true,

        // Specific agent assignment
        "email": "[email protected]"
    }
}

Example successful response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "detail": "Agent has assigned to the conversation successfully."
}

Example failed response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "detail": "Agent you are trying to assign not found."
}

Assigning Conversations To Agent Group

`POST /v2/conversations/assign_to_group/`

Assigning a conversation to an agent group.

Status Codes:

200 OK – successful
400 Bad Request – validation errors
401 Unauthorized – auth error
403 Forbidden – unauthorized request
404 Not Found – not found

Example request:

POST /v2/conversations/assign_to_group/ HTTP/1.1
Authorization: JWT ZG9udHRyeW1lIQ==
Host: api.connexease.com
Accept: application/json

{
    "uuid": "a28d98f9-66cb-444e-9661-45564deebb21",
    "group": {
        "name": "Support"
    }
}

Example successful response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "detail": "Conversation has assigned to Agent Group successfully."
}

Example failed response:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "detail": "Assignee Agent Group not found."
}

Unassigning Conversations

`POST /v2/conversations/unassign/`

Unassigning conversation

Status Codes:

200 OK – successful
400 Bad Request – validation errors
401 Unauthorized – auth error
403 Forbidden – unauthorized request

Example request:

POST /v2/conversations/unassign/ HTTP/1.1
Authorization: JWT ZG9udHRyeW1lIQ==
Host: api.connexease.com
Accept: application/json

{
    "uuid": "a28d98f9-66cb-444e-9661-45564deebb21"
}

Example successful response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "detail": "Conversation has unassigned successfully."
}

Unarchiving Conversations

`POST /v2/conversations/unarchive/`

Unassigning conversation

Status Codes:

200 OK – successful
400 Bad Request – validation errors
401 Unauthorized – auth error
403 Forbidden – unauthorized request

Example request:

POST /v2/conversations/unarchive/ HTTP/1.1
Authorization: JWT ZG9udHRyeW1lIQ==
Host: api.connexease.com
Accept: application/json

{
    "uuid": "a28d98f9-66cb-444e-9661-45564deebb21"
}

Example successful response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "detail": "Conversation has unarchived successfully."
}

Setting Types to Conversations

`POST /v2/conversations/type/`

Setting a type to conversation. 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.

Status Codes:

200 OK – successful
400 Bad Request – validation errors
403 Forbidden – unauthorized request
404 Not Found – not found
405 Method Not Allowed – not allowed

Example request:

POST /v2/conversations/type/ HTTP/1.1
Authorization: JWT ZG9udHRyeW1lIQ==
Host: api.connexease.com
Accept: application/json

{
    "uuid": "a28d98f9-66cb-444e-9661-45564deebb21",
    "type": {
        "name": "About Order",
        "sub": "Status" | null
    }
}

Example successful response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "detail": "Conversation Type has set successfully."
}

Examples failed responses:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "detail": "Conversation Type not found."
}

When trying to set the main conversation type:

HTTP/1.1 405 Method Not Allowed
Content-Type: application/json

{
    "detail": "Main Conversation Type cannot be set."
}

When trying to set a conversation type which is not allowed in the channel:

HTTP/1.1 405 Method Not Allowed
Content-Type: application/json

{
    "detail": "This conversation type cannot be used for this channel."
}

Updating The Custom Fields Of Conversation

Warning:

Use the identifier of the custom field.

`POST /v2/conversations/custom_fields/`

Updating existing custom fields for conversation.

Status Codes:

200 OK – successful
400 Bad Request – validation errors
403 Forbidden – unauthorized request
404 Not Found – not found
405 Method Not Allowed – not allowed

Example request:

POST /v2/conversations/custom_fields/ HTTP/1.1
Authorization: JWT ZG9udHRyeW1lIQ==
Host: api.connexease.com
Accept: application/json

{
    "uuid": "a28d98f9-66cb-444e-9661-45564deebb21",
    "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
        }
    }
}

Example successful response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "detail": "The custom fields of the conversation have been updated successfully."
}

Examples failed responses:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "detail": "Conversation not found."
}

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "detail": "Must provide valid custom fields and values."
}

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "info": "True",
    "error": "The entered value is not valid!"
}

Updating Customer

Warning:

For updating the CRM field please use Updating The Custom Fields of Customers API. The below method of updating CRM field will be deprecated.

`POST /v2/customers/`

Updating a customer’s info.

Status Codes:

200 OK – successful
400 Bad Request – validation errors
401 Unauthorized – auth error
403 Forbidden – unauthorized request

Example request:

POST /v2/customers/ HTTP/1.1
Authorization: JWT ZG9udHRyeW1lIQ==
Host: api.connexease.com
Accept: application/json

{
    "uuid": "f28a92f9-66cb-444e-9661-45564deebb21",
    "customer": {
        "name": "John Doe - A23F0004C",
        "crm": "A23F0004C",
        "telegram": "john_doe",
        "facebook": "john_doe",
        "email": "[email protected]",
        "instagram": "john_doe",
        "twitter": "john_doe"
    }
}

Example successful response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "detail": "Customer info has updated successfully."
}

Example failed response:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "detail": "You're not allowed to modify the customer you are trying to access."
}

Updating The Custom Fields of Customers

`POST /v2/customers/`

Updating a customer’s custom fields.

Status Codes:

200 OK – successful
400 Bad Request – validation errors
401 Unauthorized – auth error
403 Forbidden – unauthorized request

Example request:

POST /v2/customers/ HTTP/1.1
Authorization: JWT ZG9udHRyeW1lIQ==
Host: api.connexease.com
Accept: application/json

{
    "uuid": "f28a92f9-66cb-444e-9661-45564deebb21",
    "customer": {
        "custom_fields": {
            "crm_id_field": {
                "value": "value"
            },
            "a5163f43-68a6-4ee1-8f6a-58ac592acf58": {
                "value": "value"
            }
        }
    }
}

Example successful response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "detail": "Customer info has updated successfully."
}

Example failed response:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "detail": "You're not allowed to modify the customer you are trying to access."
}

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "info": "True",
    "error": "The entered value is not valid!"
}

Fetching Feedbacks

`GET /reports/feedbacks/`

Fetching feedbacks between specified dates.

Status Codes:

200 OK – successful
400 Bad Request – validation errors
401 Unauthorized – auth error
403 Forbidden – unauthorized request

Example request:

GET /reports/feedbacks/type=nps&start_date=2019-01-01T00:00:00.000001Z&end_date=2019-01-07T23:59:59.000001Z HTTP/1.1
Authorization: JWT ZG9udHRyeW1lIQ==
Host: api.connexease.com

Query Parameters:

type (string) – emoji, nps (All types if not given.)
channel (string) – Channel UUID. (All channels if not given.)
start_date (string) – ISO 8601 formatted date time string for start date.
end_date (string) – ISO 8601 formatted date time string for end date.

Example successful response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "feedbacks": [
        {
            "created_at": "2018-07-13T07:23:54.167291Z",
            "conversation": {
                "uuid": "9fbad132-db65-1437-8625-844ca1dcfc1e",
                "type": "Whatsapp EN",
                "created_at": "2018-07-13T09:23:54.167291Z"
            },
            "channel": {
                "uuid": "9cbee132-db65-4437-8825-844ca1dcfc1e",
                "name": "Sales",
                "backend": "whatsapp"
            },
            "customer": {
                "uuid": "9cec5296-be5a-4daa-b737-d6cfab92dfc8",
                "name": "Duygu Kavak",
                "phone_number": "+905555015712",
                "email": null
            },
            "type": "nps",
            "language": "english",
            "satisfaction": 9,
            "message": "Thanks for great help!"
        },
        {
            "created_at": "2018-07-13T09:16:10.167291Z",
            "conversation": {
                "uuid": "4cbfd132-db65-1437-8625-844ca1dcfc1e",
                "type": "Whatsapp EN",
                "created_at": "2018-07-13T14:16:10.167291Z"
            },
            "channel": {
                "uuid": "9cbee132-db65-4437-8825-844ca1dcfc1e",
                "name": "Sales",
                "backend": "whatsapp"
            },
            "customer": {
                "uuid": "9cec5296-be5a-4daa-b737-d6cfab92dfc8",
                "name": "Derya Denizli",
                "phone_number": "+905445023823",
                "email": null
            },
            "type": "nps",
            "language": "english",
            "satisfaction": 5,
            "message": "It was okay."
        }
    ]
}

Example failed response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": "Maximum date range exceeded. You can not fetch messages more than a month in a single request."
}

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "detail": "Invalid Authorization header. No credentials provided."
}

Documentations

Endpoints

Getting Stats

GET /stats

Getting Reports

GET /reports/

Send Batch Message

POST /batch_send_message/

Getting Chat Based Report

GET /reports/conversations/

Fetching Messages (Streaming API)

GET /stream/messages/

Status Codes:

Query Parameters:

Creating Messages

POST /v2/messages/

Archiving Conversations

POST /v2/conversations/archive/

Assigning to Conversations

POST /v2/conversations/assign/

Assigning Conversations To Agent Group

POST /v2/conversations/assign_to_group/

Unassigning Conversations

POST /v2/conversations/unassign/

Unarchiving Conversations

POST /v2/conversations/unarchive/

Setting Types to Conversations

POST /v2/conversations/type/

Updating The Custom Fields Of Conversation

POST /v2/conversations/custom_fields/

Updating Customer

POST /v2/customers/

Updating The Custom Fields of Customers

POST /v2/customers/

Fetching Feedbacks

GET /reports/feedbacks/

On this page

`GET /stats`

`GET /reports/`

`POST /batch_send_message/`

`GET /reports/conversations/`

`GET /stream/messages/`

`POST /v2/messages/`

`POST /v2/conversations/archive/`

`POST /v2/conversations/assign/`

`POST /v2/conversations/assign_to_group/`

`POST /v2/conversations/unassign/`

`POST /v2/conversations/unarchive/`

`POST /v2/conversations/type/`

`POST /v2/conversations/custom_fields/`

`POST /v2/customers/`

`POST /v2/customers/`

`GET /reports/feedbacks/`