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

Create Template

`POST /v2/whatsapp-templates/`

Creates a new WhatsApp template message and submits it to Meta for approval.
The request body follows Meta's WhatsApp template format. channels and opt_out are Connexease-specific fields and are not sent to Meta.
You do not need access to the Connexease Dashboard or Meta Business Manager to use this endpoint.

Status Codes:

201 Created – successful
400 Bad Request – bad request
401 Unauthorized – unauthorized
403 Forbidden – forbidden

Example request:

{
  "channels": [
    "76673fea-cc71-4ff2-8129-fba01abdc1a6"
  ],
  "name": "seasonal_promotion",
  "language": "en_US",
  "category": "MARKETING",
  "components": [
    {
      "type": "HEADER",
      "format": "TEXT",
      "text": "Our sale is on!"
    },
    {
      "type": "BODY",
      "text": "Shop now, {{1}}!",
      "example": {
        "body_text": [
          ["John"]
        ]
      }
    },
    {
      "type": "FOOTER",
      "text": "Reply STOP to opt out"
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "QUICK_REPLY",
          "text": "Unsubscribe",
          "opt_out": true
        },
        {
          "type": "QUICK_REPLY",
          "text": "Continue"
        }
      ]
    }
  ]
}

Request Body Parameters:

channels (array of strings) – UUIDs of the WhatsApp channels where the template should be created. All channels must belong to the same account and the same WhatsApp Business Account (WABA). The first channel is used as the primary channel.
name (string) – The template name. Meta refers to this as the element name. The name must be unique per channel.
language (string) – Template language code, e.g. en_US.
category (string) – MARKETING, UTILITY, or AUTHENTICATION.
parameter_format (string) – Only POSITIONAL is supported. You can omit this field or set it to POSITIONAL. NAMED is not supported.
components (array) – The template content in Meta's component format.

Components:

HEADER – Supports TEXT, IMAGE, VIDEO, DOCUMENT, and LOCATION formats. For TEXT, provide text. Variable placeholders in header text are not supported. For media formats, provide example.header_handle as an array containing one publicly reachable URL. Connexease downloads the media and uploads it to Meta.
BODY – Required. Every template must contain one BODY component. Use text for the message body and {{1}}, {{2}}, etc. for variables. example.body_text must contain sample values for the variables in the same order.
FOOTER – Optional. Supports text and code_expiration_minutes. code_expiration_minutes is only valid for AUTHENTICATION templates.
BUTTONS – Contains a buttons array. Supported button types are QUICK_REPLY, PHONE_NUMBER, URL, COPY_CODE, OTP, FLOW, and REQUEST_CONTACT_INFO. Other button types, such as CATALOG, are not supported.
LIMITED_TIME_OFFER – Supports limited_time_offer.text and limited_time_offer.has_expiration.

`opt_out`

opt_out is a Connexease-specific field that can be added to a QUICK_REPLY button.
Set "opt_out": true to mark the button as the account's opt-out button.
This field is removed before the template is submitted to Meta. Meta receives the button as a regular QUICK_REPLY button.

Example successful response:

HTTP/1.1 201 Created
Content-Type: application/json

{
  "uuid": "8dfff07e-7536-4c88-b0e8-64096285ba34",
  "provider_template_id": "594425479261596",
  "category": "MARKETING"
}

Example failed response:

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

{
  "uuid": "8dfff07e-7536-4c88-b0e8-64096285ba34",
  "error": "{\"error\":{\"message\":\"Invalid parameter\", ... ,\"error_user_msg\":\"This template has too many variables for its length. Reduce the number of variables or increase the message length.\", ...}}"
}

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

{
  "detail": "You do not have permission to perform this action."
}

Checking Approval Status

This endpoint does not return the template's approval status. A newly created template is initially PENDING.ibe to the account's template-status webhook to receive status updates.

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/

Create Template

POST /v2/whatsapp-templates/

Components:

opt_out

Checking Approval Status

On this page

`GET /templates/`

`POST /template_message/single/`

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

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

`POST /v2/template/bulk/`

`POST /v2/whatsapp-templates/`

`opt_out`