Messaging

19min

﻿Overview﻿
﻿Messaging APIs﻿
The APIs in this guide are applicable for sending messages and notifications across the SMS, email, and WhatsApp channels. Check out the Mobile Push Notifications guide for sending push notifications to Android and iOS applications. 
By integrating with the Messaging Service, application developers can send messages via SMS, email, and WhatsApp. This integration provides a comprehensive set of APIs for sending messages across different channels including SMS, email, and WhatsApp. Moreover, it supports one-way and two-way messaging (WhatsApp), allowing applications to send notifications and messages to users while also receiving responses.
One-way messaging flow
Follow the steps below to send one-way messages:
Register Service Provider (Optional for SMS & Email, Required for WhatsApp):
Register new service providers by calling the CreateServiceProviders API.
When registering a new service provider for SMS, developers can choose a pinpoint provider which has configuration for Toll Free Number (TFN) & 10-Digit Long Code (A2P Registered) originator numbers configured. 
For SMS and Email:
Registering a service provider is optional.
If not provided, the default messaging service provider will be used.
For WhatsApp:
Registering a service provider is mandatory.
You need to provide the necessary credentials and configuration for the WhatsApp provider.
Create Templates:
Create templates with placeholders using the Create Templates API.
Templates define the structure and content of the messages to be sent.
Placeholders allow for dynamic content to be inserted while messages are sent.
Register Notification for admin review (optional step):
Call the CreateMessageNotifications to register notifications.
Provide the necessary details for each notification, such as:
Notification name and description
Supported channels (SMS, Email, WhatsApp)
Associated templates for each channel
Tenant admin review:
Admins can review the registered notifications submitted by app developers.
They can decide to enable or disable each notification based on their review.
Send Messages:
Call the SendMessage API to send messages without using registred notifications. 
If notifications are registered, then you need to use  the SendMessagewithNotifications to send messages. 
Provide the necessary data to populate the placeholders in the associated templates.
The messaging service will send the messages using the specified channels (SMS, Email, WhatsApp).
Retrieve the delivery status of the sent messages using the callback provided in the send message API. 
Two-way messaging flow (WhatsApp Only)
Follow the steps below to send two-way messages:
Create a Service Provider Account: Create an account with a WhatsApp service provider such as InfoBip and get the credentials.
Register Service Provider: Call the CreateServiceProvider API to provide the API keys for your service provider. 
Get Webhook: Get the inbound webhook the CreateService Provider response. 
Register Notifications for tenant admin review (optional step):
Register notifications by calling the CreateNotifications API
Provide the necessary details for each notification, such as:
Notification name and description
Supported channel (WhatsApp)
Associated templates for WhatsApp
Tenant admin review:
Admins can review the registered notifications.
They can decide to enable or disable each notification based on their review.
Send 2-way message:
Call the Send2WayMessage endpoint to send a two-way message. 
Provide the necessary data to populate the placeholders in the associated templates.
Include the recipient's phone number and any additional parameters required for the two-way message.
The messaging service will send the WhatsApp message using the specified template and await a response from the recipient.
Handle the recipient's response using the registered inbound webhook and perform any necessary actions based on the response.
﻿
Sending One-way messaging
Step 1 : Register Service Provider
﻿Note:
SMS and Email:
Registering a service provider is optional.
If not provided, the default messaging service provider will be used.
WhatsApp:
Registering a service provider is mandatory.
You need to provide the necessary credentials and configuration for the WhatsApp provider.
﻿
To register new service providers, they can call CreateServiceProviders. The registration process captures the following:
Parameter
Description
name*﻿
The unique name of the provider to be created. Example: aws-ses-external.
providerType*﻿
Provider type for which the instance is to be created. 
Example: ses.
credentials
Values of the credentials specified in the provider type. 
Example Object: OrderedMap { "accessKeyId": "someSecretKey", "region": "ap-south-1", "secretAccessKey": "secretAccessKey", "projectId": "accountIdForRef" }.
isActive
Indicates whether the provider is active or not.
isTenantDefault
Tenants can set this to true to mark set a default provider. Boolean values:
true
false
Below is a sample request for registering a service provider.
RegisterProvider
{
  "name": "aws-ses-external",
  "providerType": "ses",
  "credentials": {
    "accessKeyId": "yourAccessKeyId",
    "region": "ap-south-1",
    "secretAccessKey": "yourSecretAccessKey",
    "projectId": "yourAccountIdForReference"
   },
  "isActive": true,
  "isTenantDefault": true
}
{
  "name": "aws-ses-external",
  "providerType": "ses",
  "credentials": {
    "accessKeyId": "yourAccessKeyId",
    "region": "ap-south-1",
    "secretAccessKey": "yourSecretAccessKey",
    "projectId": "yourAccountIdForReference"
   },
  "isActive": true,
  "isTenantDefault": true
}
﻿
Step 2: Create Templates
Developers can call CreateTemplates to create message templates that include the message body with dynamic parameter placeholders. These templates support tenant- and app-level placeholders and can be reused for future purposes. When sending out messages, the SendMessage API enables the option to specify a template to use, and the Messaging service will automatically populate the placeholders with the parameter data defined in the request body. We included tables with the parameters for creating a template:
Body Parameters
The table below includes the primary template parameters :
Parameter
Description
name*﻿
The name of the template to be created. Must follow the pattern ^[a-zA-Z0-9_-]{3,50}$. Example: order-delivered.
externalRef
External template ID unique from TRAI. Applicable for SMS only. 
Example: 1243234232.
mode*﻿
The mode of the template. 
Enum: sms, email, push, or whatsapp Example: sms.
Data
The data object containing oneOf `SMSBody, EmailBody, or WhatsappBody
Template Data Object Parameters
The table below includes the parameters for SMS, email, and Whatsapp within the data object. 
SMS
Email
Whatsapp
Parameter
Description
body*﻿
Message with placeholders for SMS. Example: Dear {{name}}, your order {{OrderId}} has been delivered successfully.
senderId
The `senderId` is a unique name or standard mobile number that appears in the "from" field of text messages. If the senderId is not provided, the sender ID of the tenant configuration will be used. Example: DLHVRY.
externalRef
Unique external reference ID
originationNumber
A origination number is a standard number that will be used to send the messages. If not provided, the origination number of tenant config will be used.
﻿
Parameter
Description
body*﻿
The body of an email with placeholders.
subject
The subject of the email with placeholders.
format
data.EmailBody.format
The format of the Email template. The acceptable ENUM fields: 
 text/html 
 text/plain
from
The sender's email address following the pattern ^[a-zA-Z0-9._+\-]+@[a-zA-Z0-9.\-]+\.[a-zA-Z]{2,6}$. If not provided, the sender email of the tenant config will be used.
﻿
Parameter
Description
body*﻿
The message body with placeholders.
Example: Dear {{name}}, your order {{OrderId}} has been delivered successfully.
externalRef*﻿
The external template ID registered with the service provider. If not provided, the template cannot be used to initiate the conversation.
from
The sender's number from which messages would be sent.
media
The media options supported in WhatsApp messages, like documents or images.
media.document
The document object
media.document.url
Link of the document to be sent along with the message. Maximum document size is 100MB.
media.document.fileName
Name of the document attached
media.image
Image object
media.image.url
Link of the image to be sent along with the message. Supported image types are JPG, JPEG, PNG. Maximum image size is 5MB.
buttons
Buttons to be attached with the messages
buttons.url
Redirect URL buttons which are also attached to templated messages. Note: A maximum of 2 dynamic URL buttons are allowed in a single message.
buttons.url.value
Dynamic URL as defined on the provider. 
Example: https://abc.com/{{1}}﻿
buttons.quick_reply
Quick reply buttons as registered on the provider
buttons.quick_reply.value
Payload of a quick reply button
Below is a sample request for creating a template.
SMS
email
whataspp
{
  "name": "order-sent",
  "mode": "sms",
  "data": {
    "body": "Your Login OTP is {{otp}}",
    "externalRef": "1107900000188600009",
    "originationNumber": "+123456789"
  },
  "isActive": true,
  "tags": [
    "OS1"
  ]
}
{
  "name": "order-sent",
  "mode": "sms",
  "data": {
    "body": "Your Login OTP is {{otp}}",
    "externalRef": "1107900000188600009",
    "originationNumber": "+123456789"
  },
  "isActive": true,
  "tags": [
    "OS1"
  ]
}
﻿
Step 3: (Optional) Register notifications
To register notifications supported by your application, use the CreateNotifications API. This API allows you to specify the notification details, such as app ID, notification name, templates to use with supported channels. Refer the the Register Notifications documentation for additional details. 
Get Templates
You can use use GetAllTemplates to retrieve all message templates for a tenant, or GetTemplate to retrieve a single template by name.
Step 4: Send Messages
Developer apps can call SendMessages and specify a template to send messages. If notifications are registered, call the SendMessageNotifications endpoint to send messages with notifications. 
The messaging service will populate the template using parameter data and checks if the template is approved and notifications are enabled.  Developers can also send bulk messages by specifying multiple message objects. The SendMessages request body uses the following parameters:
sms
email
whatsapp
Parameter
Description
senderId
A Sender ID is a unique name or standard mobile number that shows in the "from" field of your text messages on your phone. If not provided, the senderId of the template will be used.
Example: DLHVRY
originationNumber
A origination number is a standard number that will be used to send the messages. If not provided, the origination number of tenant config will be used.
template*﻿
Name of the template used to send this message.
Example: order-delivery-otp
provider
Name of the config instance used for sending the message. Optional parameter. If not provided, the OS1 default provider will be used.
Example: aws-pinpoint
data
Placeholders for the message.
Example: OrderedMap { "otp": "342365" }
to*﻿
An array of Phone objects (minimum 1 item required).
to.Phone
Phone number object
to.Phone.countryCode
Country code of the phone number.
Example: 91
to.Phone.number
Phone number (minimum 4 digits, maximum 10 digits)
Example: 9812345600
callback
Provide a callback URL if you need to get the message status and errors. The messaging service does not store the status and error response.
callback.url*﻿
The callback URL Example: https://os1-test-msg-callback.requestcatcher.com/test
callback.meta
Additional metadata if applicable. 
Note:
The maximum size of recipients, including to, cc, and bcc, should not exceed 50.
Email addresses must follow the pattern: ^[a-zA-Z0-9._+\-]+@[a-zA-Z0-9.\-]+\.[a-zA-Z]{2,6}$.
Parameter
Description
template*﻿
Name of the template used to send this message.
Example: order-status-template
provider
Name of the config instance used for sending the message. Optional parameter. If not provided, the OS1 default provider will be used.
Example: aws-ses-default
from
Email address of the sender. If not provided, the sender provided in the template will be used.
Example: [email protected]﻿
replyTo
Email address to which reply emails will be sent.
Example: [email protected]﻿
to*﻿
Recipients' email addresses
to.item
Email address of a recipient
Example: [email protected]﻿
cc
Recipients to be in the CC of the email
cc.item
Email address of a CC recipient
Example: [email protected]﻿
bcc
Recipients to be in the BCC of the email
bcc.item
Email address of a BCC recipient.
Example: [email protected]﻿
data
Placeholders for the message
Example: OrderedMap { "orderId": "orders:27e03289-9654-4e62-9457-32748e34efb9", "awbNumber": "AWB123456789087", "status": "delivered" }
attachments
Attachment links. Total maximum combined size of attachments is allowed only up to 10MB. Maximum 5 attachments allowed.
Example: https://console.getos1.com/header/static/media/logo.0802580f6e1b1127d6e519f4a3cbea50.svg﻿
callback
Provide a callback URL if you need to get the message status and errors. The messaging service does not store the status and error response.
callback.url*﻿
The callback URL Example: https://os1-test-msg-callback.requestcatcher.com/test
callback.meta
Additional metadata if applicable. 
Note:
The maximum size of recipients, including to, cc, and bcc, should not exceed 50.
Email addresses must follow the pattern: ^[a-zA-Z0-9._+\-]+@[a-zA-Z0-9.\-]+\.[a-zA-Z]{2,6}$.
Parameter
Description
from
Sender's standard mobile number from which messages would be sent. If not provided, the 'from' value of the template will be used.
Example: 123324242
template*﻿
Type of template used to send this message.
Example: order-delivery-otp
provider
Name of the config instance used for sending the message. Optional parameter; if not provided, the OS1 default provider will be used.
Example: infobip
data
Placeholders for the message.
Example: OrderedMap { "otp": "342365" }
media
Media options supported in WhatsApp messages. Supported types:
documents
image
location
media.document
Document object
media.document.url
Link of the document to be sent along with the message. Maximum document size is 100MB.
media.document.fileName
Name of the document attached
media.image
Image object
media.image.url
Link of the image to be sent along with the message. Supported image types are JPG, JPEG, PNG. Maximum image size is 5MB.
media.location
Supports the latitude and longitude of a location.
media.location.latitude
The latitude of a location. 
minimum: -90
maximum: 90
media.location.longitude
The longitude of a location
minimum: -90
maximum: 90
buttons
Buttons to be attached with the messages
buttons.url
Values of the placeholders in dynamic URLs provided. Optional if the URL is static or if the URL is not added in the template. 
to
Array of recipient phone numbers (minimum 1 item required)
to.Phone
Phone number object
to.Phone.countryCode
Country code of the phone number
Example: 91
to.Phone.number
Phone number (minimum 4 digits, maximum 10 digits).
Example: 9812345600
See below for example SendMessage requests: 
SMS
Email 
WhatsApp
bulk 
SMS
email
whatsapp
bulk
{
  "sms": [
    {
      "senderId": "DLHVRY",
      "template": "order-sent",
      "provider": "tfn-provider",
      "originationNumber": "+18005551234",
      "data": {
        "otp": "342365"
      },
      "to": [
        {
          "countryCode": "1",
          "number": "5551234567"
        }
      ]
    }
  ],
  "callback": {
    "url": "https://webhook.site/75a95d9c-01f5-4ea3-81f2-84202e47396a",
    "meta": {}
  }
}
{
  "sms": [
    {
      "senderId": "DLHVRY",
      "template": "order-sent",
      "provider": "tfn-provider",
      "originationNumber": "+18005551234",
      "data": {
        "otp": "342365"
      },
      "to": [
        {
          "countryCode": "1",
          "number": "5551234567"
        }
      ]
    }
  ],
  "callback": {
    "url": "https://webhook.site/75a95d9c-01f5-4ea3-81f2-84202e47396a",
    "meta": {}
  }
}
﻿
﻿
Sending 2-way messaging (WhatsApp)
The messaging service supports 2-way messages for WhatsApp. The application can use this feature to send messages for which it expects a response. The user's response will be delivered to the registered webhook, allowing the application to receive and process the response accordingly. Follow the steps below to configure and send 2-way messages: 
Step 1: Create Service Provider Account
Create an account with a WhatsApp service provider such as InfoBip and get the credentials.
Step 2: Register a Service Provider
Call the CreateServiceProvider API to provide the API keys for your service provider.
Body Parameters
Parameter
Description
name*﻿
The unique name of the provider to be created. Example: aws-ses-external.
providerType*﻿
Provider type for which the instance is to be created. 
Example: ses.
credentials
Values of the credentials specified in the provider type. 
Example Object: OrderedMap { "accessKeyId": "someSecretKey", "region": "ap-south-1", "secretAccessKey": "secretAccessKey", "projectId": "accountIdForRef" }.
isActive
Indicates whether the provider is active or not.
isTenantDefault
Tenants can set this to true to mark set a default provider. Boolean values:
true
false
Example Request
The following request registers Infobip as a service provider for WhatsApp messaging. You would need to obtain the necessary credentials such as your clientId and secret. 
RegisterProvider
{
  "name": "test-infobip",
  "providerType": "infobip",
  "credentials": {
    "clientId": "your-client-id",
    "clientSecret": "your-client-secret",
    "apiBaseUrl": "https://api.infobip.com"
  },
  "isActive": true,
  "isTenantDefault": true
}
{
  "name": "test-infobip",
  "providerType": "infobip",
  "credentials": {
    "clientId": "your-client-id",
    "clientSecret": "your-client-secret",
    "apiBaseUrl": "https://api.infobip.com"
  },
  "isActive": true,
  "isTenantDefault": true
}
﻿
In the CreateServiceProvider response, you'll get the inbound webhook endpoint. Use this webhook to register this url with the service provider to configure 2-way messaging. 
Example response
JSON
{
  "data": {
    "name": "my-whatsapp-provider",
    "inboundWebhookUrl": "https://example.com/core/api/v1/messaging-service/webhooks/whatsapp/my-whatsapp-provider/communications"
  },
  "request": {
    "uri": "/providers",
    "method": "POST",
    "queryString": "",
    "body": {
      "name": "test-infobip",
      "providerType": "infobip",
      "credentials": {
        "clientId": "your-client-id",
        "clientSecret": "your-client-secret",
        "apiBaseUrl": "https://api.infobip.com"
      },
      "isActive": true,
      "isTenantDefault": false
    }
  }
}
{
  "data": {
    "name": "my-whatsapp-provider",
    "inboundWebhookUrl": "https://example.com/core/api/v1/messaging-service/webhooks/whatsapp/my-whatsapp-provider/communications"
  },
  "request": {
    "uri": "/providers",
    "method": "POST",
    "queryString": "",
    "body": {
      "name": "test-infobip",
      "providerType": "infobip",
      "credentials": {
        "clientId": "your-client-id",
        "clientSecret": "your-client-secret",
        "apiBaseUrl": "https://api.infobip.com"
      },
      "isActive": true,
      "isTenantDefault": false
    }
  }
}
﻿
Step 3: (Optional) Register notifications
To register notifications supported by your application, use the CreateNotifications API. This API allows you to specify the notification details, such as app ID, notification name, templates to use with supported channels. Refer the the Register Notifications documentation for additional details. 
Step 4: Send two-way message
Call the Send2WayMessage  endpoint to send a two-way message. The request supports the following media types for WhatsApp messages:
Supported media types
The messaging service supports the following media types for WhatsApp messages:
Text: Plain text messages.
Images: URL link of the image to include with the message. The supported media types are JPG, JPEG, PNG images with a maximum size of 5MB.
Documents: URL link of the document to send along with the message. The supported file types are PDF, DOC, and DOCX with a maximum size of 100MB.
Interactive buttons: Quick reply buttons and URL buttons for interactive messaging.
To include media in a WhatsApp message, specify the media details in the media object of the SendTwoWayMessage  API request.
Body Parameters
Parameter
Description
from
Sender's standard mobile number from which messages would be sent. If not provided then from of template or tenant-config will be used.
message*﻿
oneOf -> TemplatedMessage, CustomMessage
provider
Name of config instance used for send message. Optional parameter if not provided os1 default provider will be used.
to*﻿
Phone number object containing countryCode and number fields.
acceptedResponses
Array of expected responses from the user. Will be redirected to the app by associated webhook url.
dynamicResponseRegex
If expected response belongs to specific format then would get compared with provided pattern and redirected using defaultInbound webhook.
webhook
Other configured webhooks for the response of this message, including defaultInbound, status, and invalidResponse webhooks.
responseTimeout
Time in seconds till when response from the user can be acknowledged and redirected to the app. Maximum allowed is up to 6 hrs.
context
Additional data which will be sent along with the webhook responses back to app, maximum size is 100kb.
errorMessage
Text to be forwarded to user in case of invalid response i.e. response does not match any of accepted responses.
Example request
The following request demonstrates a 2-way WhatsApp message that includes an order confirmation template, media attachments (document and image), a URL button, and a callback URL for message delivery details.
2-way message
{
  "from": "123324242",
  "message": {
    "template": "order-delivery-otp",
    "data": {
      "otp": "342365"
    },
    "media": {
      "document": {
        "url": "https://example.com/docs/file.pdf",
        "fileName": "Delivery Instructions.pdf"
      },
      "image": {
        "url": "https://example.com/images/map.jpg"
      },
      "location": {
        "latitude": 37.7749,
        "longitude": -122.4194
      }
    },
    "buttons": [
      "Track Order",
      "Contact Support"
    ]
  },
  "provider": "infobip",
  "to": {
    "countryCode": "91",
    "number": "9812345600"
  },
  "acceptedResponses": [
    {
      "messages": [
        "1",
        "Order Received"
      ],
      "webhook": {
        "url": "https://example.com/webhooks/response",
        "secret": "dXNlcm5hbWU6cGFzc3dvcmQ="
      }
    }
  ],
  "dynamicResponseRegex": "^\\d{6}$",
  "webhook": {
    "defaultInbound": {
      "url": "https://example.com/webhooks/",
      "secret": "c2VjcmV0LWtleQ=="
    },
    "status": {
      "url": "https://example.com/webhooks/status",
      "secret": "c3RhdHVzLXNlY3JldA=="
    },
    "invalidResponse": {
      "url": "https://example.com/webhooks/invalid",
      "secret": "aW52YWxpZC1zZWNyZXQ="
    }
  },
  "responseTimeout": 300,
  "context": {
    "orderId": "ORDER1234",
    "customerId": "CUST5678"
  },
  "errorMessage": "Please provide a valid response!"
}
{
  "from": "123324242",
  "message": {
    "template": "order-delivery-otp",
    "data": {
      "otp": "342365"
    },
    "media": {
      "document": {
        "url": "https://example.com/docs/file.pdf",
        "fileName": "Delivery Instructions.pdf"
      },
      "image": {
        "url": "https://example.com/images/map.jpg"
      },
      "location": {
        "latitude": 37.7749,
        "longitude": -122.4194
      }
    },
    "buttons": [
      "Track Order",
      "Contact Support"
    ]
  },
  "provider": "infobip",
  "to": {
    "countryCode": "91",
    "number": "9812345600"
  },
  "acceptedResponses": [
    {
      "messages": [
        "1",
        "Order Received"
      ],
      "webhook": {
        "url": "https://example.com/webhooks/response",
        "secret": "dXNlcm5hbWU6cGFzc3dvcmQ="
      }
    }
  ],
  "dynamicResponseRegex": "^\\d{6}$",
  "webhook": {
    "defaultInbound": {
      "url": "https://example.com/webhooks/",
      "secret": "c2VjcmV0LWtleQ=="
    },
    "status": {
      "url": "https://example.com/webhooks/status",
      "secret": "c3RhdHVzLXNlY3JldA=="
    },
    "invalidResponse": {
      "url": "https://example.com/webhooks/invalid",
      "secret": "aW52YWxpZC1zZWNyZXQ="
    }
  },
  "responseTimeout": 300,
  "context": {
    "orderId": "ORDER1234",
    "customerId": "CUST5678"
  },
  "errorMessage": "Please provide a valid response!"
}
﻿
In the above example:
from: The sender's number is "123324242".
template: The message template being used is "order-delivery-otp".
provider: The WhatsApp messaging provider is "infobip".
media: The message includes a PDF document and an image.
The PDF document has a URL of "https://example.comdocs/file.pdf" and a file name of "Delivery Instructions.pdf"
The image has a URL of "https://example.com/product-image.jpg"
buttons: The message includes a URL button with a dynamic URL containing the "Track Order" and “Contact Support” buttons.
to: The recipient's phone number is "9876543210" with a country code of "91".
webhook: Specifies the details for handing the accepted response: "https://example.com/webhooks/".
acceptedResponse: An array of expected or accepted responses from the recipient. 
﻿

Parameter	Description
name*	The unique name of the provider to be created. Example: aws-ses-external.
providerType*	Provider type for which the instance is to be created. Example: ses.
credentials	Values of the credentials specified in the provider type. Example Object: OrderedMap { "accessKeyId": "someSecretKey", "region": "ap-south-1", "secretAccessKey": "secretAccessKey", "projectId": "accountIdForRef" }.
isActive	Indicates whether the provider is active or not.
isTenantDefault	Tenants can set this to true to mark set a default provider. Boolean values: true false

Parameter	Description
name*	The name of the template to be created. Must follow the pattern ^[a-zA-Z0-9_-]{3,50}$. Example: order-delivered.
externalRef	External template ID unique from TRAI. Applicable for SMS only. Example: 1243234232.
mode*	The mode of the template. Enum: sms, email, push, or whatsapp Example: sms.
Data	The data object containing oneOf `SMSBody, EmailBody, or WhatsappBody

Parameter	Description
body*	Message with placeholders for SMS. Example: Dear {{name}}, your order {{OrderId}} has been delivered successfully.
senderId	The `senderId` is a unique name or standard mobile number that appears in the "from" field of text messages. If the senderId is not provided, the sender ID of the tenant configuration will be used. Example: DLHVRY.
externalRef	Unique external reference ID
originationNumber	A origination number is a standard number that will be used to send the messages. If not provided, the origination number of tenant config will be used.

Parameter	Description
body*	The body of an email with placeholders.
subject	The subject of the email with placeholders.
format	data.EmailBody.format The format of the Email template. The acceptable ENUM fields: text/html text/plain
from	The sender's email address following the pattern ^[a-zA-Z0-9._+\-]+@[a-zA-Z0-9.\-]+\.[a-zA-Z]{2,6}$. If not provided, the sender email of the tenant config will be used.

Parameter	Description
body*	The message body with placeholders. Example: Dear {{name}}, your order {{OrderId}} has been delivered successfully.
externalRef*	The external template ID registered with the service provider. If not provided, the template cannot be used to initiate the conversation.
from	The sender's number from which messages would be sent.
media	The media options supported in WhatsApp messages, like documents or images.
media.document	The document object
media.document.url	Link of the document to be sent along with the message. Maximum document size is 100MB.
media.document.fileName	Name of the document attached
media.image	Image object
media.image.url	Link of the image to be sent along with the message. Supported image types are JPG, JPEG, PNG. Maximum image size is 5MB.
buttons	Buttons to be attached with the messages
buttons.url	Redirect URL buttons which are also attached to templated messages. Note: A maximum of 2 dynamic URL buttons are allowed in a single message.
buttons.url.value	Dynamic URL as defined on the provider. Example: https://abc.com/{{1}}
buttons.quick_reply	Quick reply buttons as registered on the provider
buttons.quick_reply.value	Payload of a quick reply button

Parameter	Description
senderId	A Sender ID is a unique name or standard mobile number that shows in the "from" field of your text messages on your phone. If not provided, the senderId of the template will be used. Example: DLHVRY
originationNumber	A origination number is a standard number that will be used to send the messages. If not provided, the origination number of tenant config will be used.
template*	Name of the template used to send this message. Example: order-delivery-otp
provider	Name of the config instance used for sending the message. Optional parameter. If not provided, the OS1 default provider will be used. Example: aws-pinpoint
data	Placeholders for the message. Example: OrderedMap { "otp": "342365" }
to*	An array of Phone objects (minimum 1 item required).
to.Phone	Phone number object
to.Phone.countryCode	Country code of the phone number. Example: 91
to.Phone.number	Phone number (minimum 4 digits, maximum 10 digits) Example: 9812345600
callback	Provide a callback URL if you need to get the message status and errors. The messaging service does not store the status and error response.
callback.url*	The callback URL Example: https://os1-test-msg-callback.requestcatcher.com/test
callback.meta	Additional metadata if applicable.

Parameter	Description
template*	Name of the template used to send this message. Example: order-status-template
provider	Name of the config instance used for sending the message. Optional parameter. If not provided, the OS1 default provider will be used. Example: aws-ses-default
from	Email address of the sender. If not provided, the sender provided in the template will be used. Example: [email protected]
replyTo	Email address to which reply emails will be sent. Example: [email protected]
to*	Recipients' email addresses
to.item	Email address of a recipient Example: [email protected]
cc	Recipients to be in the CC of the email
cc.item	Email address of a CC recipient Example: [email protected]
bcc	Recipients to be in the BCC of the email
bcc.item	Email address of a BCC recipient. Example: [email protected]
data	Placeholders for the message Example: OrderedMap { "orderId": "orders:27e03289-9654-4e62-9457-32748e34efb9", "awbNumber": "AWB123456789087", "status": "delivered" }
attachments	Attachment links. Total maximum combined size of attachments is allowed only up to 10MB. Maximum 5 attachments allowed. Example: https://console.getos1.com/header/static/media/logo.0802580f6e1b1127d6e519f4a3cbea50.svg
callback	Provide a callback URL if you need to get the message status and errors. The messaging service does not store the status and error response.
callback.url*	The callback URL Example: https://os1-test-msg-callback.requestcatcher.com/test
callback.meta	Additional metadata if applicable.

Parameter	Description
from	Sender's standard mobile number from which messages would be sent. If not provided, the 'from' value of the template will be used. Example: 123324242
template*	Type of template used to send this message. Example: order-delivery-otp
provider	Name of the config instance used for sending the message. Optional parameter; if not provided, the OS1 default provider will be used. Example: infobip
data	Placeholders for the message. Example: OrderedMap { "otp": "342365" }
media	Media options supported in WhatsApp messages. Supported types: documents image location
media.document	Document object
media.document.url	Link of the document to be sent along with the message. Maximum document size is 100MB.
media.document.fileName	Name of the document attached
media.image	Image object
media.image.url	Link of the image to be sent along with the message. Supported image types are JPG, JPEG, PNG. Maximum image size is 5MB.
media.location	Supports the latitude and longitude of a location.
media.location.latitude	The latitude of a location. minimum: -90 maximum: 90
media.location.longitude	The longitude of a location minimum: -90 maximum: 90
buttons	Buttons to be attached with the messages
buttons.url	Values of the placeholders in dynamic URLs provided. Optional if the URL is static or if the URL is not added in the template.
to	Array of recipient phone numbers (minimum 1 item required)
to.Phone	Phone number object
to.Phone.countryCode	Country code of the phone number Example: 91
to.Phone.number	Phone number (minimum 4 digits, maximum 10 digits). Example: 9812345600

Parameter	Description
name*	The unique name of the provider to be created. Example: aws-ses-external.
providerType*	Provider type for which the instance is to be created. Example: ses.
credentials	Values of the credentials specified in the provider type. Example Object: OrderedMap { "accessKeyId": "someSecretKey", "region": "ap-south-1", "secretAccessKey": "secretAccessKey", "projectId": "accountIdForRef" }.
isActive	Indicates whether the provider is active or not.
isTenantDefault	Tenants can set this to true to mark set a default provider. Boolean values: true false

Parameter	Description
from	Sender's standard mobile number from which messages would be sent. If not provided then from of template or tenant-config will be used.
message*	oneOf -> TemplatedMessage, CustomMessage
provider	Name of config instance used for send message. Optional parameter if not provided os1 default provider will be used.
to*	Phone number object containing countryCode and number fields.
acceptedResponses	Array of expected responses from the user. Will be redirected to the app by associated webhook url.
dynamicResponseRegex	If expected response belongs to specific format then would get compared with provided pattern and redirected using defaultInbound webhook.
webhook	Other configured webhooks for the response of this message, including defaultInbound, status, and invalidResponse webhooks.
responseTimeout	Time in seconds till when response from the user can be acknowledged and redirected to the app. Maximum allowed is up to 6 hrs.
context	Additional data which will be sent along with the webhook responses back to app, maximum size is 100kb.
errorMessage	Text to be forwarded to user in case of invalid response i.e. response does not match any of accepted responses.

Updated 28 Jun 2024

Did this page help you?

Use Cases and Features

Messaging

﻿Overview﻿

One-way messaging flow

Two-way messaging flow (WhatsApp Only)

Sending One-way messaging

Step 1 : Register Service Provider

Step 2: Create Templates

Step 3: (Optional) Register notifications

Get Templates

Step 4: Send Messages

Sending 2-way messaging (WhatsApp)

Step 1: Create Service Provider Account

Step 2: Register a Service Provider

Step 3: (Optional) Register notifications

Step 4: Send two-way message

Overview