{"info":{"_postman_id":"6a511095-12e2-4a88-b317-590a6b88785e","name":"BPCC SMS/MMS API","description":"

The SMS/MMS API allows external applications to send messages using text-capable access numbers of the Bright Pattern platform and through supported messenger integrations. This API also enables tracking the delivery status of these messages, regardless of the channel used.

This document specifies the corresponding REST API methods, with example requests and responses. You can load this API into the Postman API Development Environment to interact with the API with your own access tokens.

Note the following:

The user account used for authentication of the SMS/MMS API requests must have the privilege Use SMS/MMS API.
A 200 OK response to a Send Message request will always show the message status as queued. The actual delivery status can be verified using the Get Message method with a slight delay
The only records created in BPCC for the messages sent via this API will be records in the Carrier Usage reports.

Possible replies to the messages sent via the API can be directed to a chat service associated with the access number or messenger integration specified by the sender ID (field From:) in the Send Message request. If it is important that you receive and process possible replies, consider sending your messages within the service hours and stop sending them well in advance of service closure.

If replies are still received outside of the service hours, you can configure your scenario to:

Use the Send Message+ scenario block to send an automatic reply advising the customer of the service hours.
\n
Copy the content of the message to an Email scenario block and send this email to someone who can follow up the next day.
\n

\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[],"owner":"6711197","collectionId":"6a511095-12e2-4a88-b317-590a6b88785e","publishedId":"S1ETRbny","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"EF5B25"},"publishDate":"2019-04-19T20:15:10.000Z"},"item":[{"name":"Authentication","item":[{"name":"Get Access Token","id":"e4eebf68-a59a-4aa4-b9e3-6c0cc53d49dd","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","name":"Content-Type","type":"text","value":"application/x-www-form-urlencoded"}],"body":{"mode":"urlencoded","urlencoded":[{"key":"client_id","value":"admin","description":"

Username of a BP user authorized to use SMS/MMS API.

\n","type":"text"},{"key":"client_secret","value":"TeOrWMZ2hFfktGkdap5PLzAzknV9oICRqpfziHkAHc93rnZJZQ3W4aBLLn07LGki\n","description":"

API secret key generated for the above user.

\n","type":"text"},{"key":"scope","value":"yourcompany.brightpattern.com","description":"

Your contact center URL, e.g., example.brightpattern.com

\n","type":"text"},{"key":"grant_type","value":"client_credentials","description":"

Grant type. Must be set to client_credentials.

\n","type":"text"}]},"url":"https://:tenant-url/configapi/v2/oauth/token","description":"

Returns an access token that will be used to authenticate each subsequent request made via this API.

\n","urlObject":{"protocol":"https","port":"tenant-url","path":["configapi","v2","oauth","token"],"query":[],"variable":[{"type":"string","value":"yourcompany.brightpattern.com","key":"tenant-url"}]}},"response":[{"id":"af695b20-7840-4e81-a115-fd8ab20d8780","name":"Get Access Token","originalRequest":{"method":"POST","header":[{"key":"Content-Type","name":"Content-Type","value":"application/x-www-form-urlencoded","type":"text"}],"body":{"mode":"urlencoded","urlencoded":[{"key":"client_id","value":"sasha","type":"text"},{"key":"client_secret","value":"FHjeyOt6LWS7jMvNb6tcjyuU3KDYlG2NjeI6vJBLV72VnLrwexA3imSkkQjSwLuv","type":"text"},{"key":"scope","value":"sasha.brightpattern.com","type":"text"},{"key":"grant_type","value":"client_credentials","type":"text"}]},"url":{"raw":"https:/:tenant-URL/configapi/v2/oauth/token","host":["https"],"port":"","path":[":tenant-URL","configapi","v2","oauth","token"],"variable":[{"key":"tenant-URL","value":"sasha.brightpattern.com"}]}},"_postman_previewlanguage":"Text","header":[],"cookie":[],"responseTime":null,"body":"{\n \"access_token\": \"15490315E83EBC929978DB0AE84D0AC63F0DC38AAB701A949FDEF6054E4A1AF9\",\n \"token_type\": \"Bearer\",\n \"expires_in\": \"3600\",\n \"scope\": \"sasha.brightpattern.com\"\n}"}],"_postman_id":"e4eebf68-a59a-4aa4-b9e3-6c0cc53d49dd"}],"id":"49c63d86-f055-4c8b-a299-f45abf1e255c","description":"

The OAuth 2.0 Client Credentials Grant is used to authenticate clients of this API. The authenticated user is checked for having appropriate privileges to perform the requested operation. The complete list of privileges can be found here. Privileges are assigned to users via one or more Roles.

To obtain an access token:

Login to your BPCC configuraiton portal.
\n
Navigate to Users page.
\n
Select or create a user with privilege Use SMS/MMS API.
\n
Click the Generate button to generate an API secret key. Copy the generated key and note the username for the next steps.
\n
Use the Get Access Token method to obtain an access token. Set the client_id to the above username and client_secret to the generated API secrect key.
\n
Use the value of access_token returned in the response to set the Authorization: Bearer [access token] header of each subsequent request made via the BPCC SMS/MMS API.
\n

\n","event":[{"listen":"prerequest","script":{"id":"e213003b-d60c-44dc-bba7-134258c88e7b","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"ce2c8c67-50c7-4fe1-8330-1c2ce18efcd8","type":"text/javascript","exec":[""]}}],"_postman_id":"49c63d86-f055-4c8b-a299-f45abf1e255c"},{"name":"SMS/MMS Messaging","item":[{"name":"Send Message","id":"9d340efd-6bb5-478f-b0b3-be5170d4509e","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":false},"method":"POST","header":[{"key":"Content-Type","name":"Content-Type","type":"text","value":"application/json"}],"body":{"mode":"raw","raw":"{\r\n \"To\": \"+5219843111460\",\r\n \"Body\": \"Sending a test message for BPCC SMS-MMS API.\",\r\n \"From\": \"16502505674\",\r\n \"MediaURLs\": \r\n [\r\n \"https://www.leithcars.com/assets/shared/CustomHTMLFiles/Responsive/MRP/Ford/2017/Mustang/images/2017-Ford-Mustang-01.jpg\"\r\n ]\r\n}"},"url":"https:/:tenant-url/clientweb/smsapi/v1/Messages","description":"

Sends an SMS, MMS, or messenger integration message to the designated recipient.

Parameters

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parameter	Description
To	Destination number or recipient identifier. Mandatory. - For messages via SMS or MMS: the destination number in E.164 format. - For messages via a messenger integration: the destination expressed in the format :, for example `viber:Akj8ntzD7CVmB3Q7V2JqSB==` or `whatsapp:5552223456`
From	Origin number or messenger integration ID. Mandatory. - For messages via SMS or MMS: Must be specified in E.164 format. The number must be configured in BPCC as an access number of Text Out type. If you intend to process possible replies, this number must also be specified as an SMS/MMS access number for the messaging scenario entry that directs such replies to a chat service. Alphanumeric Sender IDs are not currently supported. - For messages via a messenger integration: the origin integration expressed in the format :, for example `whatsapp:76BD05F0-FB19-4C3A-BA7C-30150B8D9826` or `viber:3A07AE4D-6D3E-4AA7-8417-0EE6B34824C9`.
Body	Text of the message to be sent. Mandatory for SMS (text-only) or messenger integration messages. Optional for MMS messages if the `MediaURLs` parameter is defined (see below). SMS and MMS messages longer than 160 characters will be segmented for transmission.
MediaURLs	An array of URLs for the media files to be sent in the MMS message. Optional and applies only to messages sent via MMS. May contain up to 10 items.

","urlObject":{"port":"","path":[":tenant-url","clientweb","smsapi","v1","Messages"],"host":["https"],"query":[],"variable":[{"description":{"content":"

Your contact center domain name, e.g., example.brightpattern.com.

\n","type":"text/plain"},"type":"string","value":"yourcompany.brightpattern.com","key":"tenant-url"}]}},"response":[{"id":"af915eb8-a8e9-4b1b-b0e4-3c176053e8c6","name":"Send MMS Message","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"To\": \"+5219843111460\",\r\n \"Body\": \"Sending a test MMS message for BPCC SMS-MMS API.\",\r\n \"From\": \"16502505674\",\r\n \"MediaURLs\": \r\n [\r\n \"https://www.leithcars.com/assets/shared/CustomHTMLFiles/Responsive/MRP/Ford/2017/Mustang/images/2017-Ford-Mustang-01.jpg\"\r\n ]\r\n}"},"url":{"raw":"https:/:tenant-url/clientweb/smsapi/v1/Messages","host":["https"],"port":"","path":[":tenant-url","clientweb","smsapi","v1","Messages"],"variable":[{"key":"tenant-url","value":"sasha.brightpattern.com"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Server","value":"nginx/1.14.0"},{"key":"Date","value":"Wed, 06 Feb 2019 08:24:08 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Content-Length","value":"533"},{"key":"Connection","value":"keep-alive"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Access-Control-Allow-Methods","value":"GET, POST, DELETE, PUT"},{"key":"Access-Control-Allow-Headers","value":"Content-Type"}],"cookie":[],"responseTime":null,"body":"{\n \"account_sid\": \"2B699762-370C-4F76-A684-A85B5F93DF84\",\n \"api_version\": \"1\",\n \"body\": \"Sending a test message for BPCC SMS-MMS API.\",\n \"num_segments\": \"1\",\n \"num_media\": \"0\",\n \"date_created\": \"Wed, 06 Feb 2019 08:24:08 +0000\",\n \"date_sent\": null,\n \"date_updated\": \"Wed, 06 Feb 2019 08:24:08 +0000\",\n \"direction\": \"outbound-api\",\n \"error_code\": null,\n \"error_message\": null,\n \"from\": \"16502505674\",\n \"price\": null,\n \"sid\": \"cbbb47e2-23be-452f-9b81-4a1f69300051\",\n \"status\": \"queued\",\n \"to\": \"16046496025\",\n \"uri\": \"/clientweb/smsapi/v1/Messages/cbbb47e2-23be-452f-9b81-4a1f69300051\"\n}"},{"id":"d7c136dc-c71e-4d03-b5c7-5c82939ac387","name":"Send Message with Only Mandatory Parameters","originalRequest":{"method":"POST","header":[{"key":"Content-Type","name":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"To\": \"16046496025\",\r\n \"Body\": \"Sending a test message for BPCC SMS-MMS API.\",\r\n \"From\": \"16502505674\",\r\n \"MessagingService\": \r\n}"},"url":{"raw":"https:/:tenant-url/clientweb/smsapi/v1/Messages","host":["https"],"port":"","path":[":tenant-url","clientweb","smsapi","v1","Messages"],"variable":[{"key":"tenant-url","value":"sasha.brightpattern.com"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Server","value":"nginx/1.14.0"},{"key":"Date","value":"Wed, 06 Feb 2019 08:24:08 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Content-Length","value":"533"},{"key":"Connection","value":"keep-alive"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Access-Control-Allow-Methods","value":"GET, POST, DELETE, PUT"},{"key":"Access-Control-Allow-Headers","value":"Content-Type"}],"cookie":[],"responseTime":null,"body":"{\n \"account_sid\": \"2B699762-370C-4F76-A684-A85B5F93DF84\",\n \"api_version\": \"1\",\n \"body\": \"Sending a test message for BPCC SMS-MMS API.\",\n \"num_segments\": \"1\",\n \"num_media\": \"0\",\n \"date_created\": \"Wed, 06 Feb 2019 08:24:08 +0000\",\n \"date_sent\": null,\n \"date_updated\": \"Wed, 06 Feb 2019 08:24:08 +0000\",\n \"direction\": \"outbound-api\",\n \"error_code\": null,\n \"error_message\": null,\n \"from\": \"16502505674\",\n \"price\": null,\n \"sid\": \"cbbb47e2-23be-452f-9b81-4a1f69300051\",\n \"status\": \"queued\",\n \"to\": \"16046496025\",\n \"uri\": \"/clientweb/smsapi/v1/Messages/cbbb47e2-23be-452f-9b81-4a1f69300051\"\n}"},{"id":"f428119b-f394-4c7a-8fe7-192d0f5ee3d0","name":"Send Message","originalRequest":{"method":"POST","header":[{"key":"Content-Type","name":"Content-Type","type":"text","value":"application/json"}],"body":{"mode":"raw","raw":"{\r\n \"To\": \"+5219843111460\",\r\n \"Body\": \"Test message 5\",\r\n \"From\": \"16502505674\"\r\n}"},"url":{"raw":"https://:tenant-url/clientweb/smsapi/v1/Messages","protocol":"https","port":"tenant-url","path":["clientweb","smsapi","v1","Messages"],"variable":[{"key":"tenant-url","value":"sasha.brightpattern.com"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Server","value":"nginx/1.14.0"},{"key":"Date","value":"Wed, 06 Mar 2019 20:22:33 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Content-Length","value":"506"},{"key":"Connection","value":"keep-alive"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Access-Control-Allow-Methods","value":"GET, POST, DELETE, PUT"},{"key":"Access-Control-Allow-Headers","value":"Content-Type"}],"cookie":[],"responseTime":null,"body":"{\n \"account_sid\": \"2B699762-370C-4F76-A684-A85B5F93DF84\",\n \"api_version\": \"1\",\n \"body\": \"Test message 5\",\n \"num_segments\": \"1\",\n \"num_media\": \"0\",\n \"date_created\": \"Wed, 06 Mar 2019 20:22:33 +0000\",\n \"date_sent\": null,\n \"date_updated\": \"Wed, 06 Mar 2019 20:22:33 +0000\",\n \"direction\": \"outbound-api\",\n \"error_code\": null,\n \"error_message\": null,\n \"from\": \"16502505674\",\n \"price\": null,\n \"sid\": \"23e4f784-2ccb-446c-9c84-12277d3686c0\",\n \"status\": \"queued\",\n \"to\": \"+5219843111460\",\n \"uri\": \"/clientweb/smsapi/v1/Messages/23e4f784-2ccb-446c-9c84-12277d3686c0\"\n}"}],"_postman_id":"9d340efd-6bb5-478f-b0b3-be5170d4509e"},{"name":"Get Message","id":"758db6d4-b6b0-4096-a845-a46ec1edbb04","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":false},"method":"GET","header":[],"url":"https:///clientweb/smsapi/v1/Messages/:message-sid","description":"

Gets the current status of a previously sent SMS or MMS message. Depending on the time of the request, network conditions, etc., one of the following statuses may be returned: queued, sent, delivered, failed.

\n","urlObject":{"protocol":"https","path":["clientweb","smsapi","v1","Messages",":message-sid"],"host":[""],"query":[],"variable":[{"description":{"content":"

Message identifier - taken from parameter \"sid\" of the response to a successful Send Message request.

\n","type":"text/plain"},"type":"string","value":"","key":"message-sid"}]}},"response":[{"id":"ae1c38ac-f624-48ba-9e44-37f9f049cb67","name":"Get Status of Previously Sent Message","originalRequest":{"method":"GET","header":[],"url":{"raw":"https:/:tenant-url/clientweb/smsapi/v1/Messages/:message-sid","host":["https"],"port":"","path":[":tenant-url","clientweb","smsapi","v1","Messages",":message-sid"],"variable":[{"key":"tenant-url","value":"sasha.brightpattern.com"},{"key":"message-sid","value":"cbbb47e2-23be-452f-9b81-4a1f69300051"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Server","value":"nginx/1.14.0"},{"key":"Date","value":"Wed, 06 Feb 2019 09:26:29 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Content-Length","value":"531"},{"key":"Connection","value":"keep-alive"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Access-Control-Allow-Methods","value":"GET, POST, DELETE, PUT"},{"key":"Access-Control-Allow-Headers","value":"Content-Type"}],"cookie":[],"responseTime":null,"body":"{\n \"account_sid\": \"2B699762-370C-4F76-A684-A85B5F93DF84\",\n \"api_version\": \"1\",\n \"body\": \"Sending a test message for BPCC SMS-MMS API.\",\n \"num_segments\": \"1\",\n \"num_media\": \"0\",\n \"date_created\": \"Wed, 06 Feb 2019 08:24:08 +0000\",\n \"date_sent\": \"Wed, 06 Feb 2019 08:24:08 +0000\",\n \"date_updated\": \"Wed, 06 Feb 2019 08:24:08 +0000\",\n \"direction\": \"outbound-api\",\n \"error_code\": null,\n \"error_message\": null,\n \"from\": \"16502505674\",\n \"price\": null,\n \"sid\": null,\n \"status\": \"delivered\",\n \"to\": \"16046496025\",\n \"uri\": \"/clientweb/smsapi/v1/Messages/cbbb47e2-23be-452f-9b81-4a1f69300051\"\n}"}],"_postman_id":"758db6d4-b6b0-4096-a845-a46ec1edbb04"}],"id":"355bf04a-7559-4847-9802-f622d6da1efb","description":"

These methods enable sending of SMS and MMS messages and checking the delivery status. The response parameters are explained below.

Response parameters

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parameter	Description
tenant_id	Unique identifier of your contact center in BPCC configuraiton.
api_version	API version.
body	Text of the message.
num_segments	Number of segments in the transmitted message. Messages exceeding 160 characters are transmitted in multiple segements. In the current verison of API this parameters is always set to 1.
num_media	Number of media files in the MMS message.
date_created	Timestamp of the original Send Message request.
date_sent	Timestamp of message transmission. Set to \"null\" in responses to Send Message requests. Set to actual time when the message was sent in responses to Get Message requests.
date_updated	Reserved.
direction	Always set to outboound-api.
error_code	Error code.
error_message	Error message.
from	Origin number or, if a messenger integration is being used, the messenger type and integration ID.
price	Reserved. In the current version of the API always set to null.
sid	Unique identifier of the message. Retured in response to a Send Message request and can be used in Get Message to check the delivery status of the message.
status	Status of message delivery. Possible values: queued (message queued to be sent), sent (message sent to SMS/MMS service provider but delivery not confirmed), delivered (message confirmed by SMS service provider to be delivered; currently not available for MMS), failed (message could not be sent; typically more details will be provided in error_message). Note that a 200 OK response to a Send Message request will always have status set to queued. Actual status of message delivery can be verified using the Get Message method with a slight delay.
to	Destination number or, if a messenger integration is being used, the messenger type and the messenger ID of the recipient.
uri	Reserved.

","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":false},"event":[{"listen":"prerequest","script":{"id":"2dea6d1f-d365-4be0-953a-da896709ffd1","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"f98670c1-48f2-487a-8228-aa1e58c4342e","type":"text/javascript","exec":[""]}}],"_postman_id":"355bf04a-7559-4847-9802-f622d6da1efb"}],"event":[{"listen":"prerequest","script":{"id":"d5e26752-a4a6-42fc-aa77-7b86a7c733e1","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"00d2865c-42cb-449c-8471-aa5304be811c","type":"text/javascript","exec":[""]}}]}