Canned Responses

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.

Requirements

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.

The canned response object

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 Instagram
whatsapp button A message with up to 3 reply buttons WhatsApp
whatsapp interactive_list A message with a list to choose from WhatsApp
whatsapp interactive_url A message with a button that opens a link WhatsApp
whatsapp location_request_message A message that asks the client to share their location WhatsApp

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.

List canned responses

GET https://app.alaaqat.com/api/conversations/predefined-responses

Lists your canned responses.

Query parameters

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

Response

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
    }
}

Show a canned response

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.

Create a canned response

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.

General

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.

Instagram

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"
                }
            ]
        }
    ]
}

WhatsApp

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.

Update a canned response

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 a POST request to the same URL, as multipart/form-data, with an extra field _method set to PUT.

The response is 200 OK, with the updated canned response under data.

Delete a canned response

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": []
}

Errors

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.