Promotional Messages

Promotional 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

Send promotional message templates to Arattai users. Promotional messages are marketing-oriented outbound messages for offers, product launches, seasonal announcements, and similar campaigns.

⚠
NotePromotional messages are sent using templates created in Arattai Business Platform. If the template itself has media, that template media is sent automatically - promotional messages do not support API-uploaded attachments.

Retries: ack_key is echoed back for correlation, but this API does not document deduplication behavior for repeated ack_key values. Before retrying after a timeout or a 500 operation_failed response, confirm via a webhook event or status check whether the original request already sent the message, to avoid an unintended duplicate send.

Download Promotional Messages OpenAPI Document
End Points
Send Promotional Messages API
Send Test Promotional Message API

Send Promotional Messages API 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

Send a promotional template message to an Arattai user.

Rate Limits

  • Per recipient: 15 messages per minute.
  • All recipients (platform-wide): 80 messages per second, up to 100,000 messages per day.
  • Unique recipients reachable per day: 1,000. This can be increased - contact us and we will verify and raise the limit.
  • Lock Period (wait time after the threshold is hit before consecutive requests are accepted): 1 minute.

OAuth Scope : ArattaiBusiness.messages.CREATE

Arguments

id
string
(Required)
Required string. Unique identifier of the message template.
Follow the steps to retrieve the template ID.
phone_number
string
Required string if `user_id` is not provided. Recipient phone number.
  • Format: country_code-phone_number (hyphen required)
  • Country code can optionally include a leading +
  • Examples: 91-9876543210 or +91-9876543210
  • Regex: ^\+?[1-9]\d{0,2}-\d{7,14}$
  • Maximum length: 25 characters.
user_id
string
Optional string. Required if `phone_number` is not provided. Expected recipient Arattai user ID. When supplied, Arattai cross-checks this against the recipient phone number's current Arattai user ID and rejects the send if they no longer match (recipient_identity_mismatch).
language
string
Optional string. ISO language code value.
  • Specifies the language in which the template should be sent.
  • The created template must have a corresponding language version set up in Arattai Business Platform.
  • Allowed values: en | es | fr | de | it | pt | ru | zh | ja | ko | ar | hi | ta | te | ml | bn | gu | mr | pa | th | tr | nl | pl | sv | no | da | fi | cs | el | ro | hu | vi | id | ms | he | ur | fa | sw | uk | bg | sr | sk | sl | ca | eu | gl | et | lv | lt | is | zh_tw | kn | or
  • Note: Chinese Simplified is zh, Chinese Traditional is zh_tw (lowercase, underscore)
  • Refer to Supported Languages for reference.
variables
object
Optional JSON Object. Only required if the template contains placeholders.
Key-value mapping of placeholder names defined in the template and the dynamic values to replace them with.
Only required if the template contains placeholders like {{name}}, {{orderId}}, etc.
authentication_code
string
Optional string. Only needed if the template contains a "Copy Code" or "One-tap authentication" button - not specific to the Authentication Messages API; any template type can define this kind of button.
  • Maximum length: 50 characters.
  • Allowed characters: alphanumeric and hyphens only (regex: ^[A-Za-z0-9\-]+$)
  • The value supplied here is the exact code displayed in (or copyable from) that button. Example: a seasonal-offer template with a "Copy Code" button for a discount code would set authentication_code to SAVE25.
ack_key
string
Optional string. Your own correlation key for this message. Echoed back in the send response and in every webhook event for the message. Auto-generated if omitted.
  • Allowed characters: alphanumeric, underscore, and hyphen only.
  • Maximum length: 64 characters.

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

Click to copy
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/promotions" 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/promotions") .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/promotions', 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/promotions", 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/promotions", "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/promotions"); 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/promotions"), 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/promotions" 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/promotions"); 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/promotions \ --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

Click to copy
{ "id": "2734237482371", "phone_number": "91-9876543210", "language": "en", "variables": { "customer_name": "Ryan West", "discount": "25%" }, "authentication_code": "SAVE25" }

Response Example

{ "url": "/api/v1/promotions", "type": "message", "data": { "user_id": "1001000000001001", "cost": "0.5000", "ack_key": "4460871754199040" } }
{ "code": "invalid_recipient", "message": "The recipient is not an Arattai user" }
{ "code": "user_unsubscribed_promotions", "message": "User has unsubscribed from promotional messages" }
{ "code": "no_ongoing_conversation", "message": "No ongoing conversation exists with this user_id. Send by phone_number instead" }
{ "code": "business_recipient_not_allowed", "message": "This business number is not allowed to message the recipient" }
{ "code": "unassociated_template", "message": "The template ID is not associated with this business" }
{ "code": "missing_header", "message": "Arattai-BusinessNumberId header is required" }
{ "code": "invalid_input", "message": "Either the input stream or parameter is invalid or absent" }
{ "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": "payment_required", "message": "Insufficient credits to perform this action" }
{ "code": "unauthorised", "message": "The user does not have enough permission to access the resource" }
{ "code": "promotions_disabled", "message": "Promotional messaging is disabled for this business number" }
{ "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": "too_many_requests", "message": "You have reached the maximum number of requests" }
{ "code": "operation_failed", "message": "An unexpected error occurred while processing the request" }

Send Test Promotional Message API 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

Send a promotional template message to a test customer. Credits are not billed and the send does not count against production quotas.

⚠
NoteThe recipient must be an active test customer for this business number. If not, 400 invalid_recipient is returned. A limit of 500 test messages per business number per day applies. No file attachments are supported.

mode (required): Specifies which translation version to send:
  • draft: Sends from the current draft translation.
  • published: Sends from the last approved/published translation.

Rate Limits
  • Threshold Limit (Number of API calls allowed within a minute) - 30 requests per minute
  • Lock Period (Wait time before consecutive API requests) - 1 minute


OAuth Scope : ArattaiBusiness.messages.CREATE

Arguments

phone_number
string
(Required)
Required string. The test customer's mobile number.
  • Format: country_code-phone_number (hyphen required)
  • Examples: 91-9876543210 or +91-9876543210
id
string
(Required)
Required string. Unique identifier of the message template (template reference_id).
language
string
Optional string. ISO language code value. Specifies the language in which the template should be sent.
mode
string
(Required)
Required string. Which translation version to send.
Allowed values: draft, published.
variables
object
Optional object. Key-value mapping of template placeholder names and their dynamic values.
user_id
string
Optional string. The Arattai user ID of the recipient. If provided, Arattai cross-checks the resolved user ID against this value.
ack_key
string
Optional string. Your own correlation key for this message. Echoed back in the send response and in every webhook event for the message. Auto-generated if omitted. Alphanumeric, underscore, and hyphen only. Maximum 64 characters.

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 test message will be sent.

Request Example

Click to copy
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/promotions/test" 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/promotions/test") .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/promotions/test', 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/promotions/test", 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/promotions/test", "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/promotions/test"); 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/promotions/test"), 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/promotions/test" 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/promotions/test"); 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/promotions/test \ --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

Click to copy
{ "phone_number": "91-9876543210", "id": "4XL880KMF5", "language": "en", "mode": "draft", "variables": { "item_name": "Test collar" } }

Response Example

{ "url": "/api/v1/promotions/test", "type": "message", "data": { "user_id": "1001000000001001", "ack_key": "4460871754199041" } }
{ "code": "invalid_recipient", "message": "The recipient is not an Arattai user" }
{ "code": "invalid_input", "message": "Either the input stream or parameter is invalid or absent" }
{ "code": "missing_header", "message": "Arattai-BusinessNumberId header is required" }
{ "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": "invalid_method", "message": "Invalid method" }
{ "code": "test_customer_message_limit_exceeded", "message": "This test customer has reached its daily message limit. Please try again later" }
{ "code": "operation_failed", "message": "An unexpected error occurred while processing the request" }