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 true false 155false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false 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 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 true false 265false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type template data object parameters the table below includes the parameters for sms, email, and whatsapp within the data object true false 199false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type true false 231false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type true false 211false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false 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 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 true false 206false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false 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 false 167false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false 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 false 206false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false 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 createserviceprovider api to provide the api keys for your service provider body parameters true false 155false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false 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 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 true false 222false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false left unhandled content type false 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 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