Documentations

Templates

You can send a template message to a specific phone number using WhatsApp’s Template Messages.

Warning:

You must have a Whatsapp-approved template message to use this feature. The approved template message must be saved on the Connexease platform. Contact Connexease for confirmation of the template message and registration of the approved template message on the platform.

Getting Templates

Lists your existing template messages.

`GET /templates/`

Status Codes:

200 OK – no error, Templates listed
403 Forbidden – authority error

Example request:

GET /templates/?is_active=true HTTP/1.1
Authorization: JWT ZG9udHRyeW1lIQ==
Host: api.connexease.com
Accept: application/json

Query Parameters:

is_active (string) – Optional filter attribute for active/inactive templates. Allowed values: true/false

Example successful response:

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

[
    {
        "uuid": "520a311e-988a-4d56-9acb-7132758e5114",
        "account": {
            "uuid": "a0ea3538-5e4a-4a6a-a452-6f856bb2ef53",
            "name": "Acme Ltd.",
            "is_active": true
        },
        "channels": [
            {
                "uuid": "e0b3a3f7-5447-4a4d-b4fe-d6d651611b08",
                "name": "WhatsApp Channel",
                "is_active": true
            }
        ],
        "namespace": "f4b2b57e-19ea-48f9-8a13-2d99283cda38",
        "element_name": "custom_custom",
        "is_active": true,
        "content": "Hi $1, the problem you reported on $2 has been resolved.",
        "params": {
            "fields": [
                {
                    "label": "Customer Name",
                    "placeholder": "$1"
                },
                {
                    "label": "Date",
                    "placeholder": "$2"
                }
            ]
        }
    }
]

Example failed response:

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

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

Send Template Message

`POST /template_message/single/`

Send template message to single receiver.

Status Codes:

200 OK – no error, Template message sent
202 Accepted – no error, Template message sent
400 Bad Request – error, Validation errors
403 Forbidden – authority error

Example request:

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

{
    "template_uuid": "520a311e-988a-4d56-9acb-7132758e5114",
    "channel_uuid": "b51386d9-dc40-4fdf-82f9-fb342c82c4e9",
    "params": {
        "phone_number": "905311111111",
        "name": "John",
        "customer_uuid": "94640ead-8904-45df-9392-242f0d521682",
        "unassign_and_archive": true,
        "group": "b5cad8f4-5008-47ec-b3b8-bcd7e3014da4",
        "$1": "John Doe",
        "$2": "08/10/2019"
    }
}

Warning:

If there are many variables in your template message, you should put that value in params. For example, if there are 3 variables, params should include $1, $2, $3. If there is no variable, it should only contain the phone number. If there is no phone number, it should contain the customer_uuid.

Example Media template message with media:

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

{
    "template_uuid": "520a311e-988a-4d56-9acb-7132758e5114",
    "channel_uuid": "b51386d9-dc40-4fdf-82f9-fb342c82c4e9",
    "params": {
        "phone_number": "905311111111",
        "name": "John",
        "customer_uuid": "94640ead-8904-45df-9392-242f0d521682",
        "unassign_and_archive": true,
        "group": "b5cad8f4-5008-47ec-b3b8-bcd7e3014da4",
        "$1": "John Doe",
        "$2": "08/10/2019",
        "data": {
            "url": "https://cdn.allinone.connexease.com/8a870125-7538-4ce1-8b31-a3a9e0ea26bc.jpg"
        }
    }
}

Example Media template message with location:

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

{
    "template_uuid": "520a311e-988a-4d56-9acb-7132758e5114",
    "channel_uuid": "b51386d9-dc40-4fdf-82f9-fb342c82c4e9",
    "params": {
        "phone_number": "905311111111",
        "name": "John",
        "customer_uuid": "94640ead-8904-45df-9392-242f0d521682",
        "unassign_and_archive": true,
        "group": "b5cad8f4-5008-47ec-b3b8-bcd7e3014da4",
        "$1": "John Doe",
        "$2": "08/10/2019",
        "data": {
            "latitude": "41.0321733",
            "longitude": "28.9858517"
        }
    }
}

Example Limited Time Offer (LTO) Template Message:

POST /template_message/single/ HTTP/1.1
Authorization: JWT {{your_token}}
Host: api.connexease.com
Accept: application/json

{
    "template_uuid": "520a311e-988a-4d56-9acb-7132758e5114",
    "channel_uuid": "b51386d9-dc40-4fdf-82f9-fb342c82c4e9",
    "params": {
        "phone_number": "905311111111",
        "name": "John",
        "customer_uuid": "94640ead-8904-45df-9392-242f0d521682",
        "unassign_and_archive": true,
        "group": "b5cad8f4-5008-47ec-b3b8-bcd7e3014da4",
        "data": {
            "url": "https://cdn.allinone.connexease.com/194b853c-94ad-405c-9619-29c145ef30a1.jpg",
            "filename": "offer_filename.jpg"
        },
        "{{1}}": "parameter string",
        "{{2}}": "Coupon_Code_string",
        "expiration_time": "1749976200000"
    }
}

Example successful response:

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

{
    "account": {
        "uuid": "2fbcadf6-c91a-4d1f-9ed4-d4ef5f6d1362",
        "name": "Acme Ltd"
    },
    "channel": {
        "uuid": "9cbee132-db65-4437-8825-844ca1dcfc1e",
        "name": "Whatsapp"
    },
    "uuid": "e94f00c6-0193-49db-b93b-c8931b56ba16",
    "customer": {
        "uuid": "d46fd69a-0584-41d3-8c0a-f90a4435b27b",
        "name": "John Doe",
        "mail": "[email protected]",
        "phone_number": "+90518384443"
    },
    "type": null,
    "custom_fields": {},
    "data": {
        "pdf": "PDF URL"
    },
    "created_at": "2018-03-27 10:00:19.697269+00:00",
    "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"
    }
}

Example failed response:

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

{
    "error": "Missing template message parameter!",
    "info": true
}

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

{
    "error": "Missing channel uuid parameter!",
    "info": true
}

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

{
    "error": "Missing phone number parameter!",
    "info": true
}

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

{
    "error": "There is no template available for this informations!",
    "info": true
}

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

{
    "error": "This template message is not active!",
    "info": true
}

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

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

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

{
    "detail": "Expiration time must be provided for LTO template messages!"
}

Send Bulk Template Message

`POST /accounts/{{account_uuid}}/jobs/`

Send template message to many receivers.

Status Codes:

200 OK – no error, Template messages are going to be sent.
400 Bad Request – error, Validation errors
401 Unauthorized – authority error

Example request:

POST /accounts/c4b7de0b-66bc-4505-90b9-fc196053bbfb/jobs/ HTTP/1.1
Authorization: JWT ZG9udHRyeW1lIQ==
Host: api.connexease.com
Accept: application/json

{
  "type": "1",
  "data": {
    "url": "https://cdn.allinone.connexease.com/f70159fd-8953-480b-9db6-db707eec6471.csv",
    "template_uuid": "89621dd3-484b-4213-a75d-97ef9f0ee6d",
    "channel_uuid": "b51386d9-dc40-4fdf-82f9-fb342c82c4e9",
    "params": {
      "unassign_and_archive": true,
      "group": "b5cad8f4-5008-47ec-b3b8-bcd7e3014da4",
      "data": {}
    }
  }
}

Warning:

If there are many variables in your template message, you should put that in order in an Excel file. For example, if there are 3 variables, params should include $1, $2, $3. If template message has media, like an image, put the CDN in params in data. The limitation of the CSV file and in-progress jobs can be changed from the admin panel for each account.

Example successful response:

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

{
    "id": 65,
    "uuid": "52433012-5b8a-412c-a94a-aec006de710b",
    "type": 1,
    "status": "NEW",
    "started_at": null,
    "finished_at": null,
    "data": {
        "url": "https://cdn.allinone.connexease.com/f70159fd-8953-480b-9db6-db707eec6471.csv",
        "template_uuid": "89621dd3-484b-4213-a75d-97ef9f0ee6d",
        "params": {
            "unassign_and_archive": false,
            "group": "b5cad8f4-5008-47ec-b3b8-bcd7e3014da4",
            "data": {}
        }
    },
    "progress": 0
}

Example failed response:

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

{
    "error": [
        "Something wrong with the file. Please edit it and try again."
    ],
    "info": [
        "True"
    ]
}

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

{
    "error": "Missing phone number parameter!",
    "info": true
}

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

{
    "error": "There is no template available for this information!",
    "info": true
}

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

{
    "error": [
        "The CSV file must contain a maximum of 10 lines."
    ],
    "info": [
        "True"
    ]
}

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

{
    "error": [
        "Account has 6 IN_PROGRESS background jobs. It exceeded 5."
    ],
    "info": [
        "True"
    ]
}

Example failed response:

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

{
  "detail": "Authentication credentials were not provided."
}

Getting Status of Bulk Template Messages

`GET /accounts/{{account_uuid}}/jobs/`

Lists bulk template messages that are scheduled to be sent.

Status Codes:

200 OK – no error, Result listed
401 Unauthorized – authority error

Example request:

GET /accounts/c4b7de0b-66bc-4505-90b9-fc196053bbfb/jobs/ HTTP/1.1
Authorization: JWT ZG9udHRyeW1lIQ==
Host: api.connexease.com
Accept: application/json

Example successful response:

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

[
    {
        "id": 65,
        "uuid": "52433012-5b8a-412c-a94a-aec006de710b",
        "type": 1,
        "status": "IN_PROGRESS",
        "started_at": null,
        "finished_at": null,
        "data": {
            "url": "https://cdn.allinone.connexease.com/f70159fd-8953-480b-9db6-db707eec6471.csv",
            "params": {
                "data": {},
                "group": "b5cad8f4-5008-47ec-b3b8-bcd7e3014da4",
                "unassign_and_archive": false
            },
            "template_uuid": "89621dd3-484b-4213-a75d-97ef9f0ee6d"
        },
        "progress": 55
    },
    {
        "id": 57,
        "uuid": "758b1d41-7479-4112-b62b-ce967c09041f",
        "type": 1,
        "status": "FAILED",
        "started_at": "2023-01-10T13:04:12.178662",
        "finished_at": "2023-01-10T13:04:21.071890",
        "data": {
            "url": "https://cdn.allinone.connexease.com/537e381f-e427-4d0f-acbd-568337cf492c.csv",
            "params": {
                "data": {},
                "group": "b5cad8f4-5008-47ec-b3b8-bcd7e3014da4",
                "unassign_and_archive": true
            },
            "template_uuid": "89621dd3-484b-4213-a75d-97ef9f0ee7df",
            "failure_reason": "Template message not found."
        },
        "progress": 0
    },
    {
        "id": 44,
        "uuid": "f5a833ec-40f1-4b69-b0ba-584048d8bc9e",
        "type": 1,
        "status": "FINISHED",
        "started_at": null,
        "finished_at": null,
        "data": {
            "url": "https://cdn.allinone.connexease.com/f70159fd-8953-480b-9db6-db707eec6471.csv",
            "params": {
                "data": {},
                "group": "b5cad8f4-5008-47ec-b3b8-bcd7e3014da4",
                "unassign_and_archive": false
            },
            "template_uuid": "89621dd3-484b-4213-a75d-97ef9f0ee7d"
        },
        "progress": 0
    }
]

Example failed response:

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

{
  "detail": "Authentication credentials were not provided."
}

Public Template Message Endpoints

Bulk template sending

`POST /v2/template/bulk/`

Lists bulk template messages that are scheduled to be sent.

Status Codes:

202 Accepted – no error, templates sent
400 Bad Request – missing message params, too many messages
403 Forbidden – missing or invalid credentials

Authentication: JWT token required in Authorization header. The authenticated agent must be recognized as an API user (agents without API access are rejected with 403).

Request Body Parameters
The API accepts a single messages array (max 100 items) in the JSON request. Each item in the array uses the same schema as the single-send endpoint:

messages (required array, max 100 items), each item containing:
- template_uuid (required): UUID identifier for the approved WhatsApp template
- channel_uuid (required): UUID of the WhatsApp channel
- params (required object) containing:
  - phone_number: Recipient's phone number (required if no customer_uuid)
  - customer_uuid: Existing customer identifier (alternative to phone_number)
  - name: Customer name
  - group: Group UUID for assignment
  - unassign_and_archive: Boolean to archive conversation after sending
  - $1, $2, $3...: Template variables matching the template placeholders
  - data (optional): Media content with URL or location coordinates
  - send_webhook (optional, boolean, default false): If true, conversation.created and message.created webhooks are sent for this message. Defaults to false to avoid unexpected webhook loops when sending in bulk.
    Different items in the same request may use different templates, channels, and send_webhook settings.

Example successful response:

HTTP/1.1 202 Accepted
Content-Type: application/json
{
"tid": "ab12c"
}

tid: A 5-character tracking id shared by every message in the request. Not guaranteed to be unique. It is included in the message.state_changed webhook for every message, and also in conversation.created/message.created when send_webhook was set to true for that message.

Partial Failure Response

If one or more messages in the request fail, the request still returns 202 — their errors are reported by index instead of failing the whole request:

HTTP/1.1 202 Accepted
Content-Type: application/json
{
"tid": "ab12c",
"errors": [
    {
        "index": 2,
        "error": "There is no template available for this informations!"
    }]
}

Error Responses

Error 1 (missing messages):

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "Missing messages parameter!",
"info": true
}

Error 2 (too many messages):

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "The messages array must contain a maximum of 100 items.",
"info": true
}

Error 3 (missing or invalid credentials):

HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"detail": "Invalid Authorization header. No credentials provided."
}

Error 4 (authenticated agent without API access):

HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"detail": "You do not have permission to perform this action."
}

Per-item Errors

The following error values can appear inside the errors array of an otherwise-successful (202) response, identified by the failing message's index:

"Missing params parameter!" — params missing or empty for this message
"Missing template message parameter!"
"Missing phone number parameter!"
"There is no template available for this informations!"
"This template message is not active!"
"Missing channel uuid parameter!"
"The selected channel is inactive!"
"Media information must be provided for media template messages!"
"The provided media URL is invalid!"
"Expiration time must be provided for LTO template messages!"
"Customer not found"
"Param {n} is required."
"You can't send {category} messages to this number." — customer opted out
"Template sending is not allowed for this subscription." — subscription does not allow template sending
"You do not have sufficient balance to send template messages. Please add your fund balance to send them." (account admins) / "...Please contact your account admin to add funds." (non-admin agents) — insufficient wallet balance
"An unexpected error occurred." — unclassified failure

Documentations

Templates

Getting Templates

GET /templates/

Status Codes:

Query Parameters:

Send Template Message

POST /template_message/single/

Send Bulk Template Message

POST /accounts/{{account_uuid}}/jobs/

Getting Status of Bulk Template Messages

GET /accounts/{{account_uuid}}/jobs/

Public Template Message Endpoints

Bulk template sending

POST /v2/template/bulk/

On this page

`GET /templates/`

`POST /template_message/single/`

`POST /accounts/{{account_uuid}}/jobs/`

`GET /accounts/{{account_uuid}}/jobs/`

`POST /v2/template/bulk/`