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 https //docs getos1 com/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 https //docs getos1 com/reference/create service provider configs 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 https //docs getos1 com/reference/create templates 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 https //docs getos1 com/reference/create notification 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 https //docs getos1 com/reference/send messages api to send messages without using registred notifications if notifications are registered, then you need to use the https //docs getos1 com/reference/send notifications 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 https //docs getos1 com/reference/create service provider configs 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 https //docs getos1 com/reference/create notification 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 https //docs getos1 com/reference/send two way messages 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 https //docs getos1 com/reference/create service provider configs the registration process captures the following true 155 unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type 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 https //docs getos1 com/reference/create templates 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 https //docs getos1 com/reference/send messages 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 true 265left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type template data object parameters the table below includes the parameters for sms, email, and whatsapp within the data object true 199 unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type true 231 unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type true 211left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type 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 https //docs getos1 com/reference/create notification 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 https //docs getos1 com/register notifications documentation for additional details get templates you can use use https //docs getos1 com/reference/get all templates to retrieve all message templates for a tenant, or https //docs getos1 com/reference/get template with template name to retrieve a single template by name step 4 send messages developer apps can call https //docs getos1 com/reference/send messages and specify a template to send messages if notifications are registered, call the https //docs getos1 com/reference/send notifications 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 true 206left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type 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}$ true 167left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type 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}$ true 206left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type 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 https //docs getos1 com/reference/create service provider configs api to provide the api keys for your service provider body parameters true 155 unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type 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 https //docs getos1 com/reference/create service provider configs 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 https //docs getos1 com/reference/create notification 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 https //docs getos1 com/register notifications documentation for additional details step 4 send two way message call the https //docs getos1 com/reference/send two way messages 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 https //docs getos1 com/reference/send two way messages api request body parameters true 222left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type 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 com/invoice pdf%22 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/response " acceptedresponse an array of expected or accepted responses from the recipient