Messaging

overview messaging apis 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 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 } 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 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}} 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 { "name" "order sent", "mode" "sms", "data" { "body" "your login otp is {{otp}}", "externalref" "1107900000188600009", "originationnumber" "+123456789" }, "isactive" true, "tags" \[ "os1" ] } email { "name" "order processed", "mode" "email", "data" { "body" "dear customer,\n\nyour order with the order id {{orderid}} has been delivered successfully the awb number for your order is {{awbnumber}} thank you for choosing our service \n\nsincerely,\nthe {{companyname}} team", "subject" "order delivered {{orderid}}", "format" "text/plain", "from" "" }, "isactive" true } whataspp { "name" "order delivered", "mode" "whatsapp", "data" { "body" "dear {{name}}, your order {{orderid}} has been delivered successfully ", "externalref" "1243234232", "from" "2424242842", "media" { "document" { "url" "https //example com/document pdf", "filename" "delivery receipt pdf" }, "image" { "url" "https //example com/image jpg" } }, "buttons" \[ { "url" { "value" "https //abc com/{{1}}" } }, { "quick reply" { "value" "confirm delivery" } } ] }, "isactive" true, "tags" \[ "os1", "delivery" ] } 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 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 john\@example com mailto\ john\@example com replyto email address to which reply emails will be sent example reply\@example com mailto\ reply\@example com to recipients' email addresses to item email address of a recipient example recipient\@example com mailto\ recipient\@example com cc recipients to be in the cc of the email cc item email address of a cc recipient example cc\@example com mailto\ cc\@example com bcc recipients to be in the bcc of the email bcc item email address of a bcc recipient example bcc\@example com mailto\ bcc\@example com 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 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 { "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" {} } } email { "email" \[ { "template" "order processed", "provider" "", "to" \[ "employee\@delhivery com" // update with valid email address ], "data" { "orderid" "orders 27e03289 9654 4e62 9457 32748e34efb9", "companyname" "delhivery", "awbnumber" "awb123456789087" } } ], "callback" { "url" "https //webhook site/75a95d9c 01f5 4ea3 81f2 84202e47396a", "meta" {} } } whatsapp { "whatsapp" \[ { "from" "123324242", "template" "order delivery otp", "provider" "infobip", "data" { "otp" "342365", "name" "john doe", "orderid" "xyz123" }, "media" { "document" { "url" "https //example com/document pdf", "filename" "order details pdf" }, "image" { "url" "https //example com/image jpg" } }, "buttons" \[ { "url" { "trackurl" "https //example com/track/{{orderid}}" } } ], "to" \[ { "countrycode" "+91", "number" "9812345600" }, { "countrycode" "+1", "number" "5551234567" } ] }, { "from" "987654321", "template" "order confirmation", "data" { "name" "jane smith", "orderid" "abc789" }, "to" \[ { "countrycode" "+44", "number" "7712345678" } ] } ], "callback" { "url" "https //os1 test msg callback requestcatcher com/test", "meta" {} } } bulk { "email" \[ { "template" "order processed", "provider" "", "from" "", "to" \[ "recipient1\@example com" ], "data" { "orderid" "orders 27e03289 9654 4e62 9457 32748e34efb9", "companyname" "delhivery", "awbnumber" "awb123456789087" } }, { "template" "order processed", "provider" "", "from" "", "to" \[ "recipient2\@example com" ], "data" { "orderid" "orders 27e03289 9654 4e62 9457 32748e34efb9", "companyname" "delhivery", "awbnumber" "awb123456789088" } }, { "template" "order processed", "provider" "", "from" "", "to" \[ "recipient3\@example com" ], "data" { "orderid" "orders 27e03289 9654 4e62 9457 32748e34efb9", "companyname" "delhivery", "awbnumber" "awb123456789089" } } // add more message objects as needed ], "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 } 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 { "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!" } 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" https //example com/invoice pdf%22 and a file name of "delivery instructions pdf" the image has a url of " https //example com/product image jpg 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/ https //example com/webhooks/response " acceptedresponse an array of expected or accepted responses from the recipient