API Docs
/
No Results Found
Resources
Authentication Messages

Authentication 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

Use these APIs to send authentication message templates to customers.

This API allows you to send one-time passwords (OTPs) and verification messages to users. Businesses can provide both the complete message text and a separate code parameter in the API request to facilitate secure authentication flows.

⚠
NoteTo use this API, authentication message templates must be created in Arattai Business Platform. Authentication messages do not support 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 Authentication Messages OpenAPI Document
Download
Download Arattai Business Platform OpenAPI Document
End Points
Send Authentication Messages API
Send Test Authentication Message API

Send Authentication 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

Use these APIs to send authentication message templates to customers.

This API allows you to send one-time passwords (OTPs) and verification messages to users. Businesses can provide both the complete message text and a separate code parameter in the API request to facilitate this.

⚠
NoteTo use this API, authentication message templates must be created in Arattai Business Platform.


Rate Limits
  • Per recipient: 5 messages per minute.
  • 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. The customer's mobile number to which the message will be sent.
  • 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}$
user_id
string
Optional string. The Arattai user ID of the recipient. Required if `phone_number` is not provided.
  • Can be used instead of or in addition to phone_number.
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)
variables
object
Optional JSON Object. Only required if the template contains placeholders.
Key-value mapping of placeholder names and the dynamic values to replace them with.
authentication_code
string
Optional string. Only needed if the template contains a "Copy Code" or "One-tap authentication" 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: an OTP template with a "One-tap authentication" button would set authentication_code to ABC123, the one-time passcode to verify.
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 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/authentications" 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/authentications") .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/authentications', 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/authentications", 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/authentications", "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/authentications"); 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/authentications"), 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/authentications" 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/authentications"); 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/authentications \ --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": "2374000000083015", "phone_number": "91-9876543210", "language": "en", "variables": { "customer_name": "Ryan West" }, "authentication_code": "ABC123" }

Response Example

{ "url": "/api/v1/authentications", "type": "message", "data": { "user_id": "1001000000001001", "cost": "0.5000", "ack_key": "4460871754199044" } }
{ "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": "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": "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": "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 Authentication 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 an authentication template message to a test customer. Credits are not billed and the send does not count against production quotas. File attachments are not supported.

⚠
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.

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.
language
string
Optional string. ISO language code value.
mode
string
(Required)
Required string. Which translation version to send.
Allowed values: draft, published.
authentication_code
string
Optional string. OTP or verification code to include.
  • Maximum length: 50 characters.
  • Allowed characters: alphanumeric and hyphens only (regex: ^[A-Za-z0-9\-]+$)
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.
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/authentications/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/authentications/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/authentications/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/authentications/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/authentications/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/authentications/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/authentications/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/authentications/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/authentications/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/authentications/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": "AUTH123", "language": "en", "mode": "draft", "authentication_code": "847391" }

Response Example

{ "url": "/api/v1/authentications/test", "type": "message", "data": { "user_id": "1001000000001001", "ack_key": "4460871754199045" } }
{ "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": "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" }