Display 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
Display messages are read-only layouts designed to convey text and rich visual content to customers in a clear and visually organized manner. Businesses can share summaries and structured product/catalogue data, customizable for one-to-one interactions.

Types of display layouts

Text
Image
Audio
Contact
Document
Links
Location
Video

Download Display Messages OpenAPI Document

End Points

POST

/api/v1/messages

To send a display 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 a display layout to your customer. Please note that the conversation message type must be configured in your Arattai Business Platform → Numbers → Configurations → Allow text replies.

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. Value: display. Set to display to indicate a display layout message.

type

string

(Required)

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

text - Send a plain text message, optionally with URL link preview.
image - Send an image file with an optional caption.
document - Send a document or file attachment.
audio - Send an audio file.
contact - Send a contact card with name, phone number, and address details.
link - Send a CTA button with a destination URL.
location - Send a location pin with coordinates and an optional address label.
video - Send a video file.

user_id

long

(Required)

Required. Arattai user ID of the recipient. This is the only supported recipient field for this endpoint - `phone_number` is not a usable alternative here.

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 layout type.

type: "text"

Parameter	Type	Description
`body`	Required String	Maximum length: 2000 characters. The text content to be displayed to the user.

type: "image"

Parameter	Type	Description
`link`	Required String (URL)	Publicly accessible direct download URL of the media file. Maximum file size: 1 GB (enforced by Arattai on fetch, not by this API). Download timeouts - Connection: 3 s, Read: 5 s.
`caption`	Optional String	Maximum length: 200 characters. Text shown below the image.

type: "document"

Parameter	Type	Description
`link`	Required String (URL)	Publicly accessible direct download URL of the document. The URL must point directly to a downloadable file.
`caption`	Optional String	Maximum length: 200 characters. Text shown below the document.

type: "audio"

Parameter	Type	Description
`link`	Required String (URL)	Publicly accessible direct download URL of the audio clip. The URL must point directly to a downloadable file.
`caption`	Optional String	Maximum length: 200 characters. Text shown below the audio.

type: "contact"

Parameter	Type	Description
`name`	Optional String	Full name of the contact.
`birthday`	Optional String	Birthday in dd/mm/yyyy format.
`company`	Optional JSON Object	Company information of the contact. See Attributes of company object below.
`addresses`	Optional Array, max 3	List of address objects. See Attributes of each address below.
`phones`	Optional Array, max 5	List of phone number objects. See Attributes of each phone below.
`emails`	Optional Array, max 5	List of email objects. See Attributes of each email below.
`links`	Optional Array, max 5	List of social or external profile link objects. See Attributes of each link below.

Attributes of company object:

Parameter	Type	Description
`name`	Required String	Maximum length: 250 characters. Company name.
`department`	Required String	Maximum length: 250 characters. Department within the company.
`job_title`	Optional String	Maximum length: 250 characters. Contact's job title.

Attributes of each address:

Parameter	Type	Description
`street`	Optional String	Maximum length: 250 characters. Street name of the address.
`city`	Optional String	Maximum length: 100 characters. City name.
`state`	Optional String	Maximum length: 100 characters. State or province.
`zip_code`	Optional String	Maximum length: 20 characters. Postal or zip code.
`country`	Optional String	Maximum length: 100 characters. Full country name.
`country_code`	Optional String	Maximum length: 10 characters. Two-letter ISO country code.
`type`	Optional String	Indicates home or work address. Allowed values: `home`, `work`, `personal`, `other`.

Attributes of each phone:

Parameter	Type	Description
`phone`	Required String	Maximum length: 50 characters. Phone number in international or local format.
`type`	Optional String	Phone category. Allowed values: `home`, `work`, `personal`, `other`.
`arattai_id`	Optional String	Maximum length: 100 characters. Arattai ID mapped to this phone number.

Attributes of each email:

Parameter	Type	Description
`email_id`	Optional String	Maximum length: 250 characters. Email address.
`type`	Optional String	Email category. Allowed values: `home`, `work`, `personal`, `other`.

Attributes of each link:

Parameter	Type	Description
`link`	Optional String	Maximum length: 1000 characters. The URL (website, social profile, etc.).
`type`	Optional String	Link type. Allowed values: `work`, `personal`, `fb`, `insta`.

type: "link"

Parameter	Type	Description
`url`	Required String (URL)	Public destination URL opened when the user taps the button. Must be a valid https URL.
`body`	Required String	Main message text shown above the link button.
`label`	Required String	Text shown on the CTA button.
`header`	Optional Object	Optional header shown above the body. See Attributes of header object below.
`footer`	Optional Object	Optional footer shown below the button. See Attributes of footer object below.

Attributes of header object:

Parameter	Type	Description
`type`	Optional String	Type of header content. Allowed values: `text`, `image`.
`text`	Optional String	Maximum length: 200 characters. Header text. Required when `type` is `text`.
`link`	Optional String	Maximum length: 200 characters. Header image URL. Required when `type` is `image`.

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

type: "location"

Parameter	Type	Description
`latitude`	Required String	Maximum length: 20 characters. Latitude coordinate of the location.
`longitude`	Required String	Maximum length: 20 characters. Longitude coordinate of the location.
`name`	Optional String	Maximum length: 250 characters. Display name of the location.
`address`	Optional String	Optional address of the specified location.

type: "video"

Parameter	Type	Description
`link`	Required String (URL)	Publicly accessible direct download URL of the video. Streaming platform URLs (e.g., YouTube, Vimeo) are not supported - the URL must point directly to a downloadable file.
`caption`	Optional String	Maximum length: 200 characters. Text shown below the video.

type: "sticker"

Parameter	Type	Description
`sticker_id`	Required String	Maximum length: 50 characters. ID of the sticker to send.

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": "display",
    "type": "text",
    "user_id": "53817425",
    "content": {
        "body": "Hello! We’ve updated our service hours. Visit https://example.com for details."
    }
}

{
    "category": "display",
    "type": "image",
    "user_id": "53817425",
    "content": {
        "link": "https://example.com/media/product-banner.jpg",
        "caption": "Here’s a quick look at our new collection!"
    }
}

{
    "category": "display",
    "type": "document",
    "user_id": "53817425",
    "content": {
        "link": "https://example.com/media/sample-document.pdf",
        "caption": "Download here"
    }
}

{
    "category": "display",
    "type": "audio",
    "user_id": "53817425",
    "content": {
        "link": "https://example.com/media/promo-audio.mp3"
    }
}

{
    "category": "display",
    "type": "contact",
    "user_id": "53817425",
    "content": {
        "name": "Ryan West",
        "birthday": "15/05/1990",
        "company": {
            "name": "Northbrook Retail",
            "department": "Marketing",
            "job_title": "Manager"
        },
        "addresses": [
            {
                "street": "123 Main St",
                "city": "San Francisco",
                "state": "CA",
                "zip_code": "94105",
                "country": "USA",
                "country_code": "US",
                "type": "work"
            }
        ],
        "phones": [
            {
                "phone": "14155552671",
                "type": "work",
                "arattai_id": "12345"
            }
        ],
        "emails": [
            {
                "email_id": "john.doe@example.com",
                "type": "work"
            }
        ],
        "links": [
            {
                "link": "https://linkedin.com/in/johndoe",
                "type": "work"
            }
        ]
    }
}

{
    "category": "display",
    "type": "link",
    "user_id": "53817425",
    "content": {
        "body": "Tap the button below to see dates",
        "label": "See dates",
        "url": "https://booking.zoho.in",
        "header": {
            "type": "text",
            "text": "Available Slots"
        },
        "footer": {
            "text": "Subject to availability"
        }
    }
}

{
    "category": "display",
    "type": "location",
    "user_id": "53817425",
    "content": {
        "latitude": "30.274665",
        "longitude": "-97.740350",
        "name": "Texas State Capitol",
        "address": "1100 Congress Ave, Austin, TX 78701, USA"
    }
}

{
    "category": "display",
    "type": "video",
    "user_id": "53817425",
    "content": {
        "link": "https://example.com/media/sample-video.mp4",
        "caption": "To Build Anything That Truly Lasts, It Takes Time"
    }
}

{
    "category": "display",
    "type": "sticker",
    "user_id": "53817425",
    "content": {
        "sticker_id": "sticker_001"
    }
}

Response Example

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

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

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

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

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

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

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

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

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

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

Display 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 a display 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

Display 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