Input Messages AI Tools

Open in ChatGPT

Open in ChatGPT to ask questions about this page

Open in Claude

Open in Claude to ask questions about this page

Copy as Markdown

Copy this page as markdown to use with AI assistants

View as Markdown

Open this page as markdown in a new tab

The Conversational Message APIs allow businesses to send rich, structured messages beyond plain text, supporting two-way interactions for managing ongoing chats. This is ideal for support workflows, data collection, and interactive customer journeys within Arattai.

The Conversational APIs in Arattai support two major categories of layout messages:

Display Messages - Used to clearly present information.
Input Messages - Designed to collect structured user responses.

These layouts are exchanged via the message.type field described in the schema below.

Overview
Input messages are interactive layouts used to collect structured data from customers. They allow businesses to request information such as choices, dates, and text inputs in a guided and validated format, enabling smooth, form-like interactions within the chat.

Types of input layouts

Quick reply
Interactive list
Get Location
Get Address

Download Input Messages OpenAPI Document

End Points

POST

/api/v1/messages

To send an input layout message AI Tools

Open in ChatGPT

Open in ChatGPT to ask questions about this page

Open in Claude

Open in Claude to ask questions about this page

Copy as Markdown

Copy this page as markdown to use with AI assistants

View as Markdown

Open this page as markdown in a new tab

Use the following API to send an input layout to your customer. Please note that the conversation message type must be configured in your Arattai Business Platform.

Rate Limits

Threshold Limit (Number of API calls allowed within a minute): 10 requests per minute
Lock Period (Wait time before consecutive API requests): 1 minute

Rate limits are provisional and subject to change.

OAuth Scope : ArattaiBusiness.messages.CREATE

Arguments

category

string

(Required)

Required String. Set to input to indicate an input layout message.

type

string

(Required)

Required String. The type value depends on which input layout is being sent.
Allowed values:

quick_reply - Display a message with predefined quick reply button options for the customer to select.
list - Display a message with a structured list of selectable items.
location - Request the customer's current GPS location.
address - Request the customer's address details through a structured form.

content

object

(Required)

Required JSON Object. Contains message-specific fields. The structure depends on the type field. Refer to the attribute tables below for each input layout type.

user_id

long

(Required)

Required integer. The Arattai user ID of the recipient.

type: "quick_reply"

Parameter	Type	Description
`body`	Required String	Main message text shown above the quick reply buttons.
`header`	Optional Object	Optional header shown above the body. See Attributes of header object below.
`footer`	Optional Object	Optional footer shown below the message. See Attributes of footer object below.
`options`	Required Array, max 10	List of selectable options. See Attributes of each option below.

Attributes of header object:

Parameter	Type	Description
`type`	Optional String	Type of header content. Allowed value: `image`.
`link`	Optional String	Maximum length: 200 characters. URL of the header image.

Parameter	Type	Description
`text`	Optional String	Maximum length: 200 characters. Text shown in the footer section.

Attributes of each option:

Parameter	Type	Description
`label`	Required String	Text shown on the quick reply button.
`id`	Required String	Unique ID returned when the user taps the option.

type: "list"

Parameter	Type	Description
`body`	Required String	Text prompting the user to make a selection.
`label`	Required String	Button label the user taps to open the list.
`header`	Optional Object	Optional header shown above the options. See Attributes of header object below.
`footer`	Optional Object	Optional footer shown below the options. See Attributes of footer object below.
`sections`	Required Array, max 50	Collection of grouped options in a scrollable list. See Attributes of each section below.

Attributes of header object:

Parameter	Type	Description
`text`	Optional String	Maximum length: 200 characters. Text shown in the header section.

Attributes of footer object:

Parameter	Type	Description
`text`	Optional String	Maximum length: 200 characters. Text shown in the footer section.

Attributes of each section:

Parameter	Type	Description
`title`	Required String	Maximum length: 250 characters. Title categorising the options within the section.
`options`	Required Array, max 10	List of selectable options. See Attributes of each option below.

Attributes of each option (inside section):

Parameter	Type	Description
`id`	Required String	Unique identifier returned when the user selects this option. This value is returned as `button_id` in the `chat.message.received` webhook payload.
`title`	Required String	Text displayed for the option.
`description`	Optional String	Maximum length: 200 characters. Additional context shown below the option title.

type: "location"

Parameter	Type	Description
`body`	Required String	Message asking the user to share their location.
`label`	Optional String	Button label shown to the user.

type: "address"

Parameter	Type	Description
`body`	Required String	Text shown above the input field explaining what to enter.
`label`	Required String	Label for the address submission button.
`saved_addresses`	Optional Array, max 5	List of previously saved addresses the user can choose from. See Attributes of each saved address below.
`value`	Optional JSON Object	Prefilled values for the address input. Follows the same structure as each saved address object.

Attributes of each saved address:

Parameter	Type	Description
`name`	Required String	Maximum length: 150 characters. Name of the address owner.
`phone`	Optional String	Maximum length: 15 characters. Contact phone number without country code.
`country_code`	Required String	Maximum length: 5 characters. Country calling code (e.g. 91, 1). Must be provided.
`zip_code`	Required String	Maximum length: 10 characters. Postal/Zip code.
`flat`	Required String	Maximum length: 15 characters. Flat or apartment number.
`floor`	Optional String	Maximum length: 3 characters. Floor number.
`tower`	Optional String	Maximum length: 3 characters. Tower/Building name.
`street`	Required String	Maximum length: 200 characters. Street name of address line.
`landmark`	Optional String	Maximum length: 200 characters. Nearby landmark for easier navigation.
`city`	Required String	Maximum length: 100 characters. City name.
`state`	Required String	Maximum length: 100 characters. State or province name.
`country`	Required String	Maximum length: 100 characters. Country name.
`id`	Optional String	Maximum length: 100 characters. Unique identifier for the saved address.

ack_key

string

Optional. Client-supplied message ID for idempotent retries. Auto-generated if omitted.

reply_to

string

Optional. UID of the message being replied to.

reply_from

string

Optional. Source chat ID of the reply.

Headers

Arattai-CompanyId

string

(Required)

The unique identifier of the company for this request.

Arattai-BusinessNumberId

string

(Required)

The unique identifier of the business number from which the message will be sent.

This header is required for all requests.
Obtain this ID from your Arattai Business Platform dashboard.

Request Example

parameters_data='{"field1":"value1","field2":"value2"}';
headers_data = Map();
headers_data.put("Arattai-CompanyId", "SOME_STRING_VALUE");
headers_data.put("Arattai-BusinessNumberId", "SOME_STRING_VALUE");
headers_data.put("Authorization", "Bearer 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f");
response = invokeUrl
[
url: "https://business.arattai.in/api/v1/messages"
type: POST
headers: headers_data
content-type: application/json
parameters: parameters_data
connection: <connection_name>
];
info response;

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"field1\":\"value1\",\"field2\":\"value2\"}");
Request request = new Request.Builder()
  .url("https://business.arattai.in/api/v1/messages")
  .post(body)
  .addHeader("Arattai-CompanyId", "SOME_STRING_VALUE")
  .addHeader("Arattai-BusinessNumberId", "SOME_STRING_VALUE")
  .addHeader("Authorization", "Bearer 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
  .addHeader("content-type", "application/json")
  .build();

Response response = client.newCall(request).execute();

const options = {
  method: 'POST',
  headers: {
    'Arattai-CompanyId': 'SOME_STRING_VALUE',
    'Arattai-BusinessNumberId': 'SOME_STRING_VALUE',
    Authorization: 'Bearer 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f',
    'content-type': 'application/json'
  },
  body: '{"field1":"value1","field2":"value2"}'
};

fetch('https://business.arattai.in/api/v1/messages', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

import http.client

conn = http.client.HTTPSConnection("business.arattai.in")

payload = "{\"field1\":\"value1\",\"field2\":\"value2\"}"

headers = {
    'Arattai-CompanyId': "SOME_STRING_VALUE",
    'Arattai-BusinessNumberId': "SOME_STRING_VALUE",
    'Authorization': "Bearer 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f",
    'content-type': "application/json"
    }

conn.request("POST", "/api/v1/messages", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

const http = require("https");

const options = {
  "method": "POST",
  "hostname": "business.arattai.in",
  "port": null,
  "path": "/api/v1/messages",
  "headers": {
    "Arattai-CompanyId": "SOME_STRING_VALUE",
    "Arattai-BusinessNumberId": "SOME_STRING_VALUE",
    "Authorization": "Bearer 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f",
    "content-type": "application/json"
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.write(JSON.stringify({field1: 'value1', field2: 'value2'}));
req.end();

var client = new RestClient("https://business.arattai.in/api/v1/messages");
var request = new RestRequest(Method.POST);
request.AddHeader("Arattai-CompanyId", "SOME_STRING_VALUE");
request.AddHeader("Arattai-BusinessNumberId", "SOME_STRING_VALUE");
request.AddHeader("Authorization", "Bearer 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f");
request.AddHeader("content-type", "application/json");
request.AddParameter("application/json", "{\"field1\":\"value1\",\"field2\":\"value2\"}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

var client = new HttpClient();
var request = new HttpRequestMessage
{
    Method = HttpMethod.Post,
    RequestUri = new Uri("https://business.arattai.in/api/v1/messages"),
    Headers =
    {
        { "Arattai-CompanyId", "SOME_STRING_VALUE" },
        { "Arattai-BusinessNumberId", "SOME_STRING_VALUE" },
        { "Authorization", "Bearer 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f" },
    },
    Content = new StringContent("{\"field1\":\"value1\",\"field2\":\"value2\"}")
    {
        Headers =
        {
            ContentType = new MediaTypeHeaderValue("application/json")
        }
    }
};
using (var response = await client.SendAsync(request))
{
    response.EnsureSuccessStatusCode();
    var body = await response.Content.ReadAsStringAsync();
    Console.WriteLine(body);
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io/ioutil"
)

func main() {

	url := "https://business.arattai.in/api/v1/messages"

	payload := strings.NewReader("{\"field1\":\"value1\",\"field2\":\"value2\"}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Arattai-CompanyId", "SOME_STRING_VALUE")
	req.Header.Add("Arattai-BusinessNumberId", "SOME_STRING_VALUE")
	req.Header.Add("Authorization", "Bearer 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
	req.Header.Add("content-type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := ioutil.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

const data = JSON.stringify({
  "field1": "value1",
  "field2": "value2"
});

const xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://business.arattai.in/api/v1/messages");
xhr.setRequestHeader("Arattai-CompanyId", "SOME_STRING_VALUE");
xhr.setRequestHeader("Arattai-BusinessNumberId", "SOME_STRING_VALUE");
xhr.setRequestHeader("Authorization", "Bearer 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f");
xhr.setRequestHeader("content-type", "application/json");

xhr.send(data);

curl --request POST \
  --url https://business.arattai.in/api/v1/messages \
  --header 'Arattai-BusinessNumberId: SOME_STRING_VALUE' \
  --header 'Arattai-CompanyId: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f' \
  --header 'content-type: application/json' \
  --data '{"field1":"value1","field2":"value2"}'

Body Parameters

{
    "category": "input",
    "type": "quick_reply",
    "user_id": "53817425",
    "content": {
        "body": "Choose your appointment slot",
        "header": {
            "type": "image",
            "link": "https://example.com/clinic-banner.png"
        },
        "footer": {
            "text": "Limited slots available"
        },
        "options": [
            {
                "label": "10:00 AM"
            },
            {
                "label": "11:30 AM"
            }
        ]
    }
}

{
    "category": "input",
    "type": "list",
    "user_id": "53817425",
    "content": {
        "body": "Select your service category",
        "label": "View Options",
        "header": {
            "text": "Choose a service"
        },
        "footer": {
            "text": "More categories coming soon"
        },
        "sections": [
            {
                "title": "Home Services",
                "options": [
                    {
                        "id": 1,
                        "title": "Deep Cleaning",
                        "description": "Full home sanitization"
                    },
                    {
                        "id": 2,
                        "title": "AC Service",
                        "description": "Cleaning + Gas refill"
                    }
                ]
            },
            {
                "title": "Repairs",
                "options": [
                    {
                        "id": 3,
                        "title": "Plumbing",
                        "description": ""
                    },
                    {
                        "id": 4,
                        "title": "Electrical Work",
                        "description": ""
                    }
                ]
            }
        ]
    }
}

{
    "category": "input",
    "type": "location",
    "user_id": "53817425",
    "content": {
        "body": "Share your location so we can assign the nearest delivery partner.",
        "label": "Send Location"
    }
}

{
    "category": "input",
    "type": "address",
    "user_id": "53817425",
    "content": {
        "body": "Enter your delivery address",
        "label": "Provide address"
    }
}

{
    "category": "input",
    "type": "address",
    "user_id": "53817425",
    "content": {
        "body": "Enter your delivery address",
        "label": "Provide address",
        "saved_addresses": [
            {
                "name": "Ryan West",
                "phone": "918919191",
                "zip_code": "282828",
                "country_code": "+91",
                "flat": "",
                "floor": "",
                "tower": "",
                "street": "",
                "landmark": "",
                "city": "",
                "state": "",
                "country": "",
                "id": "address_1"
            }
        ]
    }
}

{
    "category": "input",
    "type": "address",
    "user_id": "53817425",
    "content": {
        "body": "Enter your delivery address",
        "label": "Provide address",
        "value": {
            "name": "Ryan West",
            "phone": "+999999",
            "zip_code": "292929",
            "country_code": "+91",
            "flat": "",
            "floor": "",
            "tower": "",
            "street": "",
            "landmark": "",
            "city": "",
            "state": "",
            "country": "",
            "id": "address_1"
        }
    }
}

Response Example

{
    "url": "/api/v1/messages",
    "type": "message",
    "data": {
        "user_id": "53817425",
        "ack_key": "4460871754199047"
    }
}

{
    "url": "/api/v1/messages",
    "type": "message",
    "data": {
        "user_id": "53817425",
        "ack_key": "4460871754199047"
    }
}

{
    "url": "/api/v1/messages",
    "type": "message",
    "data": {
        "user_id": "53817425",
        "ack_key": "4460871754199047"
    }
}

{
    "url": "/api/v1/messages",
    "type": "message",
    "data": {
        "user_id": "53817425",
        "ack_key": "4460871754199047"
    }
}

{
    "url": "/api/v1/messages",
    "type": "message",
    "data": {
        "user_id": "53817425",
        "ack_key": "4460871754199047"
    }
}

{
    "url": "/api/v1/messages",
    "type": "message",
    "data": {
        "user_id": "53817425",
        "ack_key": "4460871754199047"
    }
}

{
    "code": "business_message_window_expired",
    "message": "Business-initiated messages are not allowed because the user has not sent any message within the last 48 hours"
}

{
    "code": "invalid_input",
    "message": "Either the input stream or parameter is invalid or absent"
}

{
    "code": "invalid_recipient",
    "message": "The recipient is not an Arattai user"
}

{
    "code": "url_not_accessible",
    "message": "The media URL provided is not accessible"
}

{
    "code": "invalid_file_type",
    "message": "The media type is not supported by Arattai"
}

{
    "code": "no_ongoing_conversation",
    "message": "No ongoing conversation exists with this user. Conversational messages can only be sent within an active conversation window"
}

{
    "code": "business_recipient_not_allowed",
    "message": "This business number is not allowed to message the recipient"
}

{
    "code": "unsupported_file",
    "message": "File is not supported"
}

{
    "code": "empty_file_not_allowed",
    "message": "The uploaded file is empty"
}

{
    "code": "missing_header",
    "message": "A required header is missing from the request"
}

{
    "code": "too_many_requests",
    "message": "You have reached the maximum number of requests"
}

{
    "code": "invalid_oauthtoken",
    "message": "You are not authenticated to do this operation"
}

{
    "code": "unauthorised",
    "message": "The user does not have enough permission to access the resource."
}

{
    "code": "invalid_method",
    "message": "Invalid method"
}

{
    "code": "recipient_identity_mismatch",
    "message": "The provided user_id does not match the current Arattai user for this phone number. The number may now belong to a different user"
}

{
    "code": "file_size_too_large",
    "message": "Size of the file is too large"
}

{
    "code": "operation_failed",
    "message": "An unexpected error occurred while processing the request"
}

Input Messages AI Tools Open in ChatGPT Open in ChatGPT to ask questions about this page Open in Claude Open in Claude to ask questions about this page Copy as Markdown Copy this page as markdown to use with AI assistants View as Markdown Open this page as markdown in a new tab

To send an input layout message AI Tools Open in ChatGPT Open in ChatGPT to ask questions about this page Open in Claude Open in Claude to ask questions about this page Copy as Markdown Copy this page as markdown to use with AI assistants View as Markdown Open this page as markdown in a new tab

Arguments

Headers

Input Messages AI Tools

Open in ChatGPT

Open in ChatGPT to ask questions about this page

Open in Claude

Open in Claude to ask questions about this page

Copy as Markdown

Copy this page as markdown to use with AI assistants

View as Markdown

Open this page as markdown in a new tab