A canned response is an answer your team writes once and sends in two clicks from the inbox, and that workflows send automatically. Through the API, an integration can keep these answers in step with another system: update the prices in a reply when your catalogue changes, or add a response for every new branch.
To learn how team members use canned responses in the app, see Canned Responses.
| Action | Token ability | Team member permission |
|---|---|---|
| List and show | predefined-response-index |
View Canned Responses |
| Create | predefined-response-create |
Create New Canned Response |
| Update | predefined-response-update |
Edit Canned Response |
| Delete | predefined-response-delete |
Delete Canned Response |
The number of canned responses an account can have depends on the plan. See the plans on the pricing page.
Every canned response has a type, which decides what it holds and where it can be sent:
type |
subtype |
Holds | Sent on |
|---|---|---|---|
general |
- | Text, attachments, or both | Every channel |
instagram |
generic |
A carousel of cards | |
whatsapp |
button |
A message with up to 3 reply buttons | |
whatsapp |
interactive_list |
A message with a list to choose from | |
whatsapp |
interactive_url |
A message with a button that opens a link | |
whatsapp |
location_request_message |
A message that asks the client to share their location |
The content is under template. Its shape follows the type, as the examples in Create a canned response
show.
{
"_id": "6659e1f2a3b4c5d6e7f8a901",
"name": "Opening hours",
"type": "general",
"subtype": null,
"template": {
"type": "general",
"description": "We are open every day from 9 am to 9 pm. Our menu is attached.",
"attachments": [
{
"url": "https://files.example.com/spring-menu.pdf",
"media_type": "application/pdf",
"type": "application",
"subtype": "pdf",
"file_size": 245760,
"caption": null,
"file_name": "spring-menu.pdf",
"source": "upload",
"purpose": "media",
"unavailable": false
}
]
},
"account_id": 1024,
"updated_at": "2026-10-20T09:30:00.000000Z",
"created_at": "2026-10-20T09:30:00.000000Z"
}
Canned responses have no variables. The text is sent exactly as written.
GET https://app.alaaqat.com/api/conversations/predefined-responses
Lists your canned responses.
This endpoint accepts the Pagination parameters.
| Key | Type | Default | Description |
|---|---|---|---|
| search | string | - | Search by name. |
| filters[types][] | string | - | Only responses of this type. Repeat it for several types. |
| filters[workflow_connection] | string | - | connected for the responses a workflow sends, not_connected for the others. |
GET https://app.alaaqat.com/api/conversations/predefined-responses?filters[types][]=whatsapp&search=order
200 OK, or 206 Partial Content when more pages follow. Each response also carries workflows: the workflows
that send it, with their _id, name and whether they are active.
{
"data": [
{
"_id": "6659e1f2a3b4c5d6e7f8a902",
"name": "Order ready",
"type": "whatsapp",
"subtype": "button",
"template": {
"type": "button",
"header": {
"type": "text",
"text": "Your order is ready"
},
"body": {
"text": "Would you like it delivered, or will you pick it up?"
},
"action": {
"buttons": [
{
"type": "reply",
"reply": {
"id": "delivery",
"title": "Deliver it"
}
},
{
"type": "reply",
"reply": {
"id": "pickup",
"title": "I'll pick it up"
}
}
]
}
},
"account_id": 1024,
"updated_at": "2026-10-20T09:40:00.000000Z",
"created_at": "2026-10-20T09:40:00.000000Z",
"workflows": [
{
"_id": "665ae1f2a3b4c5d6e7f8a911",
"name": "Order status replies",
"is_active": true
}
]
}
],
"links": {
"first": "https://app.alaaqat.com/api/conversations/predefined-responses?page=1",
"last": "https://app.alaaqat.com/api/conversations/predefined-responses?page=1",
"prev": null,
"next": null
},
"meta": {
"current_page": 1,
"from": 1,
"last_page": 1,
"path": "https://app.alaaqat.com/api/conversations/predefined-responses",
"per_page": 15,
"to": 1,
"total": 1
}
}
GET https://app.alaaqat.com/api/conversations/predefined-responses/{_id}
Where _id is the canned response's _id. Returns one canned response under data, in the shape of
the canned response object. It needs the same ability as the list, predefined-response-index.
POST https://app.alaaqat.com/api/conversations/predefined-responses
Creates a canned response. Every type takes these two fields, plus the fields of its own type below:
| Field | Required | Validation | Description |
|---|---|---|---|
| name | Required | Text, up to 30 characters for general and up to 150 for the other types |
The name your team picks the response by. Clients don't see it. |
| type | Required | general, instagram or whatsapp |
What the response holds. |
A response that holds files, such as an attachment or a card image, must be sent as multipart/form-data. A
response with text only can be sent as JSON.
The response is 201 Created, with the new canned response under data.
| Field | Required | Validation | Description |
|---|---|---|---|
| description | Required without attachments |
Text, at least 3 characters | The text of the response. |
| attachments[] | Required without description |
Files, each at least 1 KB | Files sent with the text. |
Attachments can be images (PNG, JPG), videos (MP4), audio (AAC, WAV, MP3, OGG, WebM), and documents (PDF, Word, Excel, PowerPoint). An image can be about 5 MB, a video about 25 MB, and an audio file about 16 MB. Alaaqat converts audio to a format every channel accepts.
Sent as multipart/form-data:
name: Opening hours
type: general
description: We are open every day from 9 am to 9 pm. Our menu is attached.
attachments[0]: (the file spring-menu.pdf)
The channel still applies its own file limits when the response is sent. See Sending messages.
A carousel of cards. Set subtype to generic, and describe each card under elements. Instagram shows up to 10
cards.
| Field | Required | Validation | Description |
|---|---|---|---|
| subtype | Required | generic |
|
| elements[].title | Required | Text, up to 80 characters | The card's title. |
| elements[].subtitle | Optional | Text, 3 to 80 characters | The line under the title. |
| elements[].image | Optional | An image file, up to 16 MB | The card's picture. |
| elements[].default_action.type | Optional | web_url |
Opens a link when the client taps the card. |
| elements[].default_action.url | Required with default_action |
A URL | The link the card opens. |
| elements[].buttons[] | Optional | Up to 3 buttons | The card's buttons. |
| elements[].buttons[].type | Required | web_url, postback or phone_number |
Opens a link, sends a reply back, or calls a number. |
| elements[].buttons[].title | Required | Text, up to 20 characters | The button's label. |
| elements[].buttons[].url | Required for web_url |
A URL | The link the button opens. |
| elements[].buttons[].payload | Required for phone_number |
Text | The phone number to call. |
{
"name": "Chair offer",
"type": "instagram",
"subtype": "generic",
"elements": [
{
"title": "Ergonomic office chair",
"subtitle": "Adjustable height, black mesh back",
"buttons": [
{
"type": "web_url",
"title": "Order now",
"url": "https://shop.example.com/chair"
},
{
"type": "phone_number",
"title": "Call us",
"payload": "+96265000000"
}
]
}
]
}
An interactive WhatsApp message. Set subtype to one of the four kinds below. Each kind takes a body.text of up
to 1,024 characters, the main text of the message.
Reply buttons (button): the client answers by tapping a button.
| Field | Required | Validation | Description |
|---|---|---|---|
| header.type | Optional | text, image, video or document |
What the header shows. |
| header.text | Optional | Text, up to 60 characters | The header, when header.type is text. |
| header.attachment | Optional | A file | The header's file, when header.type is image, video or document. |
| body.text | Required | Text, up to 1,024 characters | The message. |
| footer.text | Optional | Text, up to 60 characters | A short line under the message. |
| action.buttons[] | Required | 1 to 3 buttons | |
| action.buttons[].reply.id | Required | Text, up to 256 characters | An ID you choose. It comes back when the client taps the button. |
| action.buttons[].reply.title | Required | Text, up to 20 characters | The button's label. |
{
"name": "Order ready",
"type": "whatsapp",
"subtype": "button",
"header": {
"type": "text",
"text": "Your order is ready"
},
"body": {
"text": "Would you like it delivered, or will you pick it up?"
},
"action": {
"buttons": [
{
"reply": {
"id": "delivery",
"title": "Deliver it"
}
},
{
"reply": {
"id": "pickup",
"title": "I'll pick it up"
}
}
]
}
}
List (interactive_list): the client opens a list and picks one row.
| Field | Required | Validation | Description |
|---|---|---|---|
| header.text | Optional | Text, up to 60 characters | A text header. |
| body.text | Required | Text, up to 1,024 characters | The message. |
| footer.text | Optional | Text, up to 60 characters | A short line under the message. |
| action.button | Required | Text, up to 20 characters | The label of the button that opens the list. |
| action.sections[] | Required | Up to 10 sections, with 10 rows in all | The groups of rows. |
| action.sections[].title | Required | Text, up to 24 characters | The section's title. |
| action.sections[].rows[].id | Required | Text, up to 200 characters | An ID you choose. It comes back when the client picks the row. |
| action.sections[].rows[].title | Required | Text, up to 24 characters | The row's title. |
| action.sections[].rows[].description | Optional | Text, up to 72 characters | A line under the row's title. |
{
"name": "Branches",
"type": "whatsapp",
"subtype": "interactive_list",
"body": {
"text": "Which branch would you like to visit?"
},
"action": {
"button": "See branches",
"sections": [
{
"title": "Amman",
"rows": [
{
"id": "abdoun",
"title": "Abdoun",
"description": "Open 9 am to 9 pm"
},
{
"id": "sweifieh",
"title": "Sweifieh",
"description": "Open 10 am to 10 pm"
}
]
}
]
}
}
Link button (interactive_url): a button that opens a web page.
| Field | Required | Validation | Description |
|---|---|---|---|
| header.type, header.text, header.attachment | Optional | As for reply buttons | The header. |
| body.text | Required | Text, up to 1,024 characters | The message. |
| footer.text | Optional | Text, up to 60 characters | A short line under the message. |
| action.parameters.display_text | Required | Text, up to 20 characters | The button's label. |
| action.parameters.url | Required | A URL | The page the button opens. |
{
"name": "Catalogue",
"type": "whatsapp",
"subtype": "interactive_url",
"body": {
"text": "Our new catalogue is out. Take a look at this season's offers."
},
"action": {
"parameters": {
"display_text": "Open catalogue",
"url": "https://shop.example.com/catalogue"
}
}
}
Location request (location_request_message): asks the client to share their location.
| Field | Required | Validation | Description |
|---|---|---|---|
| body.text | Required | Text, up to 1,024 characters | The message. |
{
"name": "Ask for location",
"type": "whatsapp",
"subtype": "location_request_message",
"body": {
"text": "Please share your location so we can send the nearest driver."
}
}
WhatsApp counts these limits in visible characters, so an emoji counts as one. Alaaqat may count some emoji as two or three, so leave some room when you use them.
PUT https://app.alaaqat.com/api/conversations/predefined-responses/{_id}
Where _id is the canned response's _id. Send the whole response again, name and type included, with the
same fields as when you created it. What you send replaces the content.
Files you don't send again are kept: leave attachments, a card's image or a header's attachment out, and the
current file stays. Send a new file in the same place to replace it.
{info} Most HTTP tools can't send files with
PUT. To replace a file, send the update as aPOSTrequest to the same URL, asmultipart/form-data, with an extra field_methodset toPUT.
The response is 200 OK, with the updated canned response under data.
DELETE https://app.alaaqat.com/api/conversations/predefined-responses/{_id}
Where _id is the canned response's _id. Deletes the response and its files.
A response that a workflow sends can't be deleted: the request is refused with 403, and the message names the
workflows. Remove the response from those workflows first.
The response is 200 OK:
{
"message": "Entity was deleted successfully.",
"data": []
}
| Status | Meaning |
|---|---|
| 402 | Your plan's limit of canned responses is reached. See the plans on the pricing page. |
| 403 | The key lacks the ability, or the team member lacks the permission. On update and delete, also when no canned response with this _id is in your account, and on delete, when a workflow sends the response. |
| 404 | On show: no canned response with this _id in your account. |
| 422 | A field failed validation, for example a missing name, a type or subtype that doesn't exist, or a text over its limit. |