diff --git a/code-samples/webhooks/quick-start/javascript/webhook-notification.js b/code-samples/webhooks/quick-start/javascript/webhook-notification.js index 5b0ce0b0..d1ea4fdc 100644 --- a/code-samples/webhooks/quick-start/javascript/webhook-notification.js +++ b/code-samples/webhooks/quick-start/javascript/webhook-notification.js @@ -56,7 +56,7 @@ async function subscribe_for_notification() { } } try { - var resp = await resplatform.post('/restapi/v1.0/subscription', params) + var resp = await platform.post('/restapi/v1.0/subscription', params) var jsonObj = await resp.json() console.log(jsonObj.id) console.log("Ready to receive incoming SMS via WebHook.") @@ -64,4 +64,4 @@ async function subscribe_for_notification() { console.error(e.message); throw e; } -} \ No newline at end of file +} diff --git a/docs/messaging/fax/sending-faxes.md b/docs/messaging/fax/sending-faxes.md index ccad6df9..e2c69b0d 100644 --- a/docs/messaging/fax/sending-faxes.md +++ b/docs/messaging/fax/sending-faxes.md @@ -72,7 +72,7 @@ The following code samples show how to send a simple single document fax. formData.append('attachment', require('fs').createReadStream('test.jpg')); try { - var resp = await platform.post('/account/~/extension/~/fax', formData) + var resp = await platform.post('/restapi/v1.0/account/~/extension/~/fax', formData) var jsonObj = await resp.json() console.log("FAX sent. Message status: " + jsonObj.messageStatus) } catch(e) { diff --git a/docs/messaging/sms/high-volume/best-practices.md b/docs/messaging/sms/high-volume/best-practices.md new file mode 100644 index 00000000..9570f70a --- /dev/null +++ b/docs/messaging/sms/high-volume/best-practices.md @@ -0,0 +1,139 @@ +# High Volume SMS Best Practices and Guidelines + +Spam message blockages and invalid phone numbers are the most common causes of having low message deliverability - the SMS performance which you aim to reach as high as possible. + +Sending text messages to invalid phone numbers is a waste of resources and money. Apparently, it decreases your message delivery rate. + +Unsolicited and harmful messages are classified as spam, and will be blocked by most wireless carriers. Sending spam messages to many recipients would trigger a carrier to block your phone number. Consequently, any message sent from that phone number will be blocked, even if the message is innocuous. + +Different wireless carriers apply different anti-spam filtering techniques, to protect their subscribers from receiving unwanted messages. Spam detection is complicated and some carriers are stricter than others. The boundary between spam and non-spam messages is fuzzy, and the criteria may change over time. + +There is no magic or trick to fool spam detections. So the only way to avoid getting your messages blocked is not to send spam messages. + +Follows are some best practices and guidelines which would help you increase your SMS performance. + +* Get recipient's permission and attention +* Increase and maintain response rate +* Include opt-out instructions +* Segment your recipient lists +* Segment your messages +* Do not send messages to opted-out recipients +* Avoid sending messages to invalid numbers +* Use single domain links +* Common sense + + +## Get recipient's permission + +Get recipient's opt-in consent before sending messages to their number. This is not only helping you avoid getting customer complaints causing future messages emanating from your number to be filtered out by their carrier, but also protecting your business from violating text messaging regulations, which may cost your business a fortune. Especially when you send marketing or other non-essential messages. + +For an implied consent, meaning that when an individual gives you their mobile phone number for some business purpose, but has not explicitly stated that they want to receive marketing text messages from you. In this case, send your first message as a request for an opt-in option. Explicitly ask the recipient to reply “Yes” to opt-in before sending your sales or promo marketing messages. If there is no reply from the recipient, consider it as an opted-out number and stop sending text messages to that phone number. + +## Increase and maintain response rate + +High response rate is the good health of your phone number. It would help wireless carriers identify that your message is expected and welcomed by the recipient. This is important especially, when you start using your high volume SMS phone number, as high response rate would help warm up your phone number reputation. + +Start your text messaging campaign by sending a brief message to introduce yourself or your business, and ask if your customers would like to learn more about your sales or your promo. E.g. 'Reply YES for more info'. Treat the first message as an opt-in or opt-out choice for your customers. + +## Include opt-out instructions + +Always provide clear opt-out instructions. Messages without opt-out instructions are likely to get marked as spam. Including opt-out instructions also ensures compliance with consumer data protection regulations. For example, add this text at the end of each message 'Text STOP to unsubscribe'. + +You don't need to add the opt-out instructions to every message sent out to your recipient. Just the first message and once in a while if you repeatedly send messages to the same recipient, would be sufficient. + +## Segment your recipient lists + +Avoid sending the same message to mass recipients. Segment your recipient lists based on customer preferences, demographics and other characteristics. Then, send relevant messages to each group to vary your content. + +## Personalize and optimized messages + +Sending a message to customers should provide a good customer experience. The message should be correctly punctuated and conveys useful information in a short and summarized manner which can be read by the recipients on-the-go. Messages that encourage recipients to respond are very effective, as they demonstrate value that you are delivering to the customer. + +If you know the recipient’s name, greet the recipient by name. For example, consider sending this message “Hi Rob, our records indicate that ...”, instead of “Our records indicate that …”. + +Excessively capitalized SMS messages look like spam, and aggressive language often leads to complaints. Also avoid using hyperbole like '100% GUARANTEED', 'COMPLETELY FREE', or 'NO CHARGE' as they tend to be filtered. + +## Segment your messages + +SMS differs from email in that the messages are very short. Do not make your SMS message an email! Sending a very long text message to mass recipients looks like spam. So, break your long message into multi-section messages, then send a brief message with response choices to receive the next messages. As a bonus, this will usually improve your response rates, too. + +**Consider this long message:** + + These arm bands will surely come in handy on your next run! Shop the deals now! + + Today's Trending Products: this and that and the others ... + + Recommended For You: this and that and that one too ... + + Click https://www.easyshopping.com to shop now or refer friends https://www.easyshopping.com/invite?utm_campaign to earn up to $100! + +Replaced with multi-section messages + + Hi, EasyShopping.com provides fun and easy way to shop online. Reply 1 to get deals, or 2 to get more info. + + Reply STOP to unsubscribe + +If your customer replies 1, send the next message with current deals + + Thank you for your interest! + + Today's Trending Products: this and that and the others ... + +If your customer replies 2, send the next message with more information + + Thank you for your interest! + + Recommended For You: this and that and that one too ... + + Visit https://www.easyshopping.com/deals to shop now or refer friends https://www.easyshopping.com/invite?utm_campaign to earn up to $100! + +## Do not send messages to opted-out recipients + +Regularly, [read opted-out](../opt-out#read-opted-out-phone-numbers) phone numbers and remove them from your recipient list. If you receive this error code `SMS-CAR-413` after sending a message to your recipient. Take serious action to remove the recipient number from your recipient list. + +Sending a text message to an opted-out recipient is violating the text messaging compliance laws, and consequently, a recipient's carrier will block your message. Keep sending text messages to an opted-out recipient may trigger the recipient's carrier to block your phone number permanently. + +## Avoid sending messages to invalid numbers + +When exporting your customer phone numbers from your contact list or your CRM system, make sure that you select the mobile number type if applicable. + +To avoid invalid phone number problems, you can use phone number validation services to detect valid mobile phone numbers. For example, using the following services to ensure the phone number type is not a landline number: + +Numverify (free): https://numverify.com + +Ekata (250 free lookups): https://ekata.com + +However, not all invalid numbers are detectable until a wireless carrier reports it as invalid. Read your [message store](../message-store#read-high-volume-message-store), preferably after sending a batch of messages, and look for messages with the “SendingFailed” or “DeliveryFailed” status with these error codes `SMS-UP-410` , `SMS-CAR-411`, `SMS-CAR-412`, check the recipient number and remove it from your recipient list. + +## Use single domain links + +If you use URLs in your message, the following are important considerations are necessary to use them successfully. + +* Use links associated with a single hostname per message +* Full domains are preferred. Link shorteners can be used but use a link shortener domain that you own. + +!!! warning "Avoid public / shared link shortener domains" + Hosted link shorteners are easy to set up and use, however you should not use a public / shared link shortener domain as the same domains are often used by attackers to mask phishing and other URLs. + + If you wish to use one for text messages, check to see the service supports using your own domain, sometimes called custom domains or vanity URLs. + + Some common public / shared domain shorteners to avoid include: + - bit.ly + - goo.gl + - tinyurl.com + - Tiny.cc + - bc.vc + - budurl.com + - Clicky.me + - is.gd + - lc.chat + - soo.gd + - s2r.co + +## Common sense + +A good rule of thumb is to put yourself in your recipient’s shoes and write a message in a way that would be compelling for you. + +What is your reaction when you receive an unsolicited message so frequently from an unknown sender? Accept it, block it or report it to your carrier? + +Are you going to click on this kind of link http://bit.ly/aX123d in a message sent by an unknown sender and expect you will win a big gift? Do you care what that link will take you to? diff --git a/docs/messaging/sms/high-volume/message-store.md b/docs/messaging/sms/high-volume/message-store.md index 18cf46b5..8bf59e3b 100644 --- a/docs/messaging/sms/high-volume/message-store.md +++ b/docs/messaging/sms/high-volume/message-store.md @@ -1,28 +1,34 @@ # High Volume SMS Message Store -The High Volume SMS message store is separate from the normal SMS (P2P) message store. +The high volume SMS message store is separate from the standard SMS (P2P) message store. Use the APIs in the table below to access your high volume SMS message store. + +| API Endpoint | Description | +|-|-| +| [`/restapi/v1.0/account/~/a2p-sms/messages`](#read-high-volume-message-store) | Read the entire high volume message store. | +| [`/restapi/v1.0/account/~/a2p-sms/batches`](#list-batches) | List all batches basic info from the entire high volume message store. | +| [`/restapi/v1.0/account/~/a2p-sms/batches/{batchId}`](#read-individual-batch) | Read a single batch basic info identified by the batch id. | +| [`/restapi/v1.0/account/~/a2p-sms/statuses?batchId=[batchId]`](#read-batch-message-statuses) | Read a batch aggregate message statuses. | +| [`/restapi/v1.0/account/~/a2p-sms/messages/{messageId}`](#read-individual-message) | Read a single message identified by the message id. | + ## Read High Volume Message Store -You can read the entire High Volume SMS message store then iterate through the `records` array in the response to parse each message's metadata. Use the `pageToken` to navigate through the entire message store if the numbers of records is greater than the maximum number of items per page. +You can read the entire high volume SMS message store then iterate through the `records` array in the response to parse each message's metadata. Use the `nextPageToken` to read the next page if the total number of records is greater than the maximum number of items per page. -| API Endpoint | Description | -|-|-| -| [`/restapi/v1.0/account/~/a2p-sms/messages`](https://developers.ringcentral.com/api-reference/High-Volume-SMS/listA2PSMS) | Read the entire High Volume message store. | -| [`/restapi/v1.0/account/~/a2p-sms/messages/{messageId}`](https://developers.ringcentral.com/api-reference/High-Volume-SMS/listA2PSMS) | Read a single message identified by a message id. | +To avoid loading the entire message store, which could be extremely large, you can use the following query parameters to control and limit the number of messages in a response. To read messages per batch, you can use the [List Batches](#list-batches) API to retrieve a list of batch Ids, then use a batch id as a filter to read messages from that batch. ### Query parameters | Filter | Description | |-|-| -| view | Read the A2P message store in "Simple" or "Detailed" mode. Detailed view will return the text message for each message item. Default value is "Simple". | -| batchId | Return only messages belong to a single batch identified by the batch id. | -| dateFrom | Return messages created after the start date and time, for example 2020-11-10T08:00:00.000Z. The default value is dateTo minus 24 hours. | -| dateTo | Return messages created before the end date time, for example 2020-11-11T08:00:00.000Z. The default value is current time. | -| phoneNumber | Return only messages which contains the specified phone numbers in either "from" or "to" field. | -| direction | Return messages with the specified direction. If not specified, both inbound and outbound messages are returned. Multiple values are accepted. | -| perPage | Indicate the page size (number of items). Default value is 1000. | -| pageToken | Return messages from a specified page. Note! Use a valid page token from the paging object. | +| `view` | Read the A2P message store in "Simple" or "Detailed" mode. Detailed view will return the text message for each message item. Default value is "Simple". | +| `batchId `| Return only messages belong to a single batch identified by the batch id. | +| `dateFrom `| Return messages created after the start date and time, for example 2020-11-10T08:00:00.000Z. The default value is dateTo minus 24 hours. | +| `dateTo `| Return messages created before the end date time, for example 2020-11-11T08:00:00.000Z. The default value is current time. | +| `phoneNumber `| Return only messages which contains the specified phone numbers in either "from" or "to" field. | +| `direction` | Return messages with the specified direction. If not specified, both inbound and outbound messages are returned. Multiple values are accepted. | +| `perPage` | Indicate the page size (number of items). Default value is 1000. | +| `pageToken` | Return messages from a specified page. Note! Use a valid page token from the paging object. | ### Sample codes @@ -72,7 +78,7 @@ You can read the entire High Volume SMS message store then iterate through the ` 'dateTo': "2021-01-31T23:59:59.999Z", 'phoneNumber': ["+16505550100"] } - resp = platform.get('/restapi/v1.0/account/~/a2p-sms/messages') + resp = platform.get('/restapi/v1.0/account/~/a2p-sms/messages', params) print resp.text() ``` @@ -232,9 +238,305 @@ You can read the entire High Volume SMS message store then iterate through the ` } ``` -## Read High Volume Individual Message +## List Batches + +You can read batches and parse the response to get a batch id and other basic info such as the status, the number of recipients, the creation date and time etcetera. You can use the following query parameters to control and limit the number of batches in a response. + +### Query parameters + +| Filter | Description | +|-|-| +| `dateFrom` | Return batches created after the start date and time, for example 2020-11-10T08:00:00.000Z. The default value is dateTo minus 24 hours. | +| `dateTo` | Return batches created before the end date time, for example 2020-11-11T08:00:00.000Z. The default value is current time. | +| `from` | Return only batches sent from the specified phone number. | +| `status` | The status of a batch. Can be _Processing_ or _Completed_. | +| `perPage` | Indicate the page size (number of items). Default value is 1000. | +| `pageToken` | Return batches from a specified page. Note! Use a valid page token from the paging object. | + + +### Sample codes + +=== "HTTP" + ```http + GET /restapi/v1.0/account/~/a2p-sms/batches?dateFrom=2021-06-20T00:00:00.000Z&dateTo=2021-06-21T23:59:59.999Z + ``` + +=== "JavaScript" + ```javascript + const RingCentral = require('@ringcentral/sdk').SDK + + var rcsdk = new RingCentral( {server: "server_url", clientId: "client_id", clientSecret: "client_secret"} ); + var platform = rcsdk.platform(); + + platform.login( {username: "username", password: "password", extension: "extension_number"} ) + + platform.on(platform.events.loginSuccess, async function(response){ + try{ + var params = { + dateFrom: '2021-06-20T00:00:00.000Z', + dateTo: '2021-06-21T23:59:59.999Z' + } + var resp = await platform.get('/restapi/v1.0/account/~/a2p-sms/batches', params) + var jsonObj = await resp.json() + console.log(jsonObj) + }catch(e){ + console.log(e.message) + } + }); + ``` + +=== "Python" + ```python + from ringcentral import SDK + + sdk = SDK( "client_id", "client_secret", "server_url" ) + platform = sdk.platform() + platform.login( "username", "extension", "password" ) + params = { + 'dateFrom': '2021-06-20T00:00:00.000Z', + 'dateTo': '2021-06-21T23:59:59.999Z' + } + resp = platform.get('/restapi/v1.0/account/~/a2p-sms/batches', params) + print resp.text() + ``` + +=== "PHP" + ```php + platform(); + $platform->login( "username", "extension_number", "password" ); + + $params = array( + 'dateFrom' => "2021-06-20T00:00:00.000Z", + 'dateTo' => "2021-06-21T23:59:59.999Z" + ); + $resp = $platform->get('/restapi/v1.0/account/~/a2p-sms/batches', $params); + print_r ($resp->json()); + ?> + ``` + +=== "Ruby" + ```ruby + require 'ringcentral' + + rc = RingCentral.new( 'client_id', 'client_secret', 'server_url') + rc.authorize( username: 'username', extension: 'extension_number', password: 'password') + + params = { + dateFrom: "2021-06-20T00:00:00.000Z", + dateTo: "2021-06-21T23:59:59.999Z" + } + resp = rc.get('/restapi/v1.0/account/~/a2p-sms/batches', params) + + puts resp.body + ``` + +### Response + +```json +{ + "records": [ + { + "id": 'b4e00b67-969f-4db4-a22d-e3ef3cec7c11', + "from": '+16505550100', + "batchSize": 100, + "processedCount": 100, + "status": 'Completed', + "creationTime": '2021-06-21T10:31:59.818028Z', + "lastModifiedTime": '2021-06-21T10:32:00.870634Z', + "rejected": [], + "cost": 0.700 + }, + { + "id": '95bc9e86-e93a-48a0-a8c0-2e6fff6d52b8', + "from": '+16505550100', + "batchSize": 50, + "processedCount": 50, + "status": 'Completed', + "creationTime": '2021-06-21T09:31:59.775224Z', + "lastModifiedTime": '2021-06-21T09:32:00.810797Z', + "rejected": [], + "cost": 0.350 + } + ] +} +``` + +## Read Individual Batch + +You can read a single batch basic info such as the status, the number of recipients, the number of processed messages etcetera. This is helpful for reading and updating a batch progress in real-time if you send a large batch which would take several hours to be completed. + +### Sample codes + +=== "HTTP" + ```http + GET /restapi/v1.0/account/~/a2p-sms/batches/b4e00b67-969f-4db4-a22d-e3ef3cecxxxx + ``` + +=== "JavaScript" + ```javascript + const RingCentral = require('@ringcentral/sdk').SDK + + var rcsdk = new RingCentral( {server: "server_url", clientId: "client_id", clientSecret: "client_secret"} ); + var platform = rcsdk.platform(); + + platform.login( {username: "username", password: "password", extension: "extension_number"} ) + + platform.on(platform.events.loginSuccess, async function(response){ + try{ + var resp = await platform.get('/restapi/v1.0/account/~/a2p-sms/batches/b4e00b67-969f-4db4-a22d-e3ef3cecxxxx') + var jsonObj = await resp.json() + console.log(jsonObj) + }catch(e){ + console.log(e.message) + } + }); + ``` + +=== "Python" + ```python + from ringcentral import SDK + + sdk = SDK( "client_id", "client_secret", "server_url" ) + platform = sdk.platform() + platform.login( "username", "extension", "password" ) + + resp = platform.get('/restapi/v1.0/account/~/a2p-sms/batches/b4e00b67-969f-4db4-a22d-e3ef3cecxxxx') + print resp.text() + ``` + +=== "PHP" + ```php + platform(); + $platform->login( "username", "extension_number", "password" ); + + $resp = $platform->get('/restapi/v1.0/account/~/a2p-sms/batches/b4e00b67-969f-4db4-a22d-e3ef3cecxxxx'); + print_r ($resp->json()); + ?> + ``` + +=== "Ruby" + ```ruby + require 'ringcentral' + + rc = RingCentral.new( 'client_id', 'client_secret', 'server_url') + rc.authorize( username: 'username', extension: 'extension_number', password: 'password') + + resp = rc.get('/restapi/v1.0/account/~/a2p-sms/batches/b4e00b67-969f-4db4-a22d-e3ef3cecxxxx') + + puts resp.body + ``` + +### Response + +```json +{ + "id": 'b4e00b67-969f-4db4-a22d-e3ef3cecxxxx', + "from": '+16505550100', + "batchSize": 100, + "processedCount": 100, + "status": 'Completed', + "creationTime": '2021-06-21T10:31:59.818028Z', + "lastModifiedTime": '2021-06-21T10:32:00.870634Z', + "rejected": [], + "cost": 0.700 +} +``` + +## Read Batch Message Statuses + +To get a quick report on message statuses in a batch, you can call this endpoint to get the aggregate message statuses and error codes (if any). If you need to detect each individual message status, use this [endpoint](#read-high-volume-message-store) instead. + +### Sample codes + +=== "HTTP" + ```http + GET /restapi/v1.0/account/~/a2p-sms/statuses?batchId=8ba42748-0e48-4459-8262-342a7483xxxx + ``` + +=== "JavaScript" + ```javascript + const RingCentral = require('@ringcentral/sdk').SDK + + var rcsdk = new RingCentral( {server: "server_url", clientId: "client_id", clientSecret: "client_secret"} ); + var platform = rcsdk.platform(); + + platform.login( {username: "username", password: "password", extension: "extension_number"} ) + + platform.on(platform.events.loginSuccess, async function(response){ + try{ + var resp = await platform.get('/restapi/v1.0/account/~/a2p-sms/statuses?batchId=8ba42748-0e48-4459-8262-342a7483xxxx') + var jsonObj = await resp.json() + console.log(JSON.stringify(jsonObj)) + }catch(e){ + console.log(e.message) + } + }); + ``` + +=== "Python" + ```python + from ringcentral import SDK + + sdk = SDK( "client_id", "client_secret", "server_url" ) + platform = sdk.platform() + platform.login( "username", "extension", "password" ) + resp = platform.get('/restapi/v1.0/account/~/a2p-sms/statuses?batchId=8ba42748-0e48-4459-8262-342a7483xxxx') + print resp.text() + ``` + +=== "PHP" + ```php + platform(); + $platform->login( "username", "extension_number", "password" ); + $resp = $platform->get('/restapi/v1.0/account/~/a2p-sms/statuses?batchId=8ba42748-0e48-4459-8262-342a7483xxxx'); + print_r ($resp->json()); + ?> + ``` + +=== "Ruby" + ```ruby + require 'ringcentral' + + rc = RingCentral.new( 'client_id', 'client_secret', 'server_url') + rc.authorize( username: 'username', extension: 'extension_number', password: 'password') + resp = rc.get('/restapi/v1.0/account/~/a2p-sms/statuses?batchId=8ba42748-0e48-4459-8262-342a7483xxxx') + + puts resp.body + ``` + +### Response + +```json +{ + "queued": { "count": 0 }, + "delivered": { "count": 2 }, + "deliveryFailed": { + "count": 0, + "errorCodeCounts": {} + }, + "sent": { "count": 0 }, + "sendingFailed": { "count": 0 } +} +``` + +## Read Individual Message -You can read the individual message details from High Volume message store using a message id. +You can read an individual message details from the high volume message store using a message id. Message ids can be retrieved from the response of this [endpoint](#read-high-volume-message-store) ### Sample codes diff --git a/docs/messaging/sms/high-volume/sending-highvolume-sms.md b/docs/messaging/sms/high-volume/sending-highvolume-sms.md index 3cca6c6a..e6c8d3e3 100755 --- a/docs/messaging/sms/high-volume/sending-highvolume-sms.md +++ b/docs/messaging/sms/high-volume/sending-highvolume-sms.md @@ -4,7 +4,9 @@ The High Volume SMS API provides a very flexible way to send multiple SMS messag !!! note "There is no limit of number of recipients in a batch. However, the maximum size of each batch is about 50MB." -## Simple Broadcast Request to send the same message to 2 recipients +### Sample codes + +Simple request to broadcast the same message to multiple recipients === "HTTP" @@ -45,7 +47,7 @@ The High Volume SMS API provides a very flexible way to send multiple SMS messag } var resp = await platform.post('/restapi/v1.0/account/~/a2p-sms/batch', requestBody) var jsonObj = await resp.json() - console.log(JSON.stringify(jsonObj)) + console.log(jsonObj) }catch(e){ console.log(e.message) } @@ -68,7 +70,7 @@ The High Volume SMS API provides a very flexible way to send multiple SMS messag { "to": ["+12125550100"] } ] } - resp = platform.get('/restapi/v1.0/account/~/a2p-sms/batch', requestBody) + resp = platform.post('/restapi/v1.0/account/~/a2p-sms/batch', requestBody) print resp.text() ``` @@ -188,6 +190,8 @@ The High Volume SMS API provides a very flexible way to send multiple SMS messag puts resp.body ``` +### Response + The code samples above would all produce a response that would appear similar to the one below. ```json @@ -210,7 +214,9 @@ The code samples above would all produce a response that would appear similar to ``` If your batch contains invalid phone numbers, you will receive the `rejected` list with content only from the response returned by sending a batch. Reading the batch status will always return an empty `rejected` array. -## Simple Request to send customized messages to 2 recipients +### Sample codes + +Simple request to send customized messages to multiple recipients === "HTTP" ```http @@ -279,7 +285,7 @@ The code samples above would all produce a response that would appear similar to } var resp = await platform.post('/restapi/v1.0/account/~/a2p-sms/batch', requestBody) var jsonObj = await resp.json() - console.log(JSON.stringify(jsonObj)) + console.log(jsonObj) }catch(e){ console.log(e.message) } @@ -423,11 +429,13 @@ The code samples above would all produce a response that would appear similar to puts resp.body ``` +### Response + The code samples above would all produce a response that would appear similar to the one below. ```json { - "id": "2157ac7d-baab-4d0e-1262-deada6c757c8", + "id": "2157ac7d-baab-4d0e-1262-deada6c7xxxx", "from": "+16505550100", "batchSize": 2, "processedCount": 0, @@ -440,7 +448,14 @@ The code samples above would all produce a response that would appear similar to ## Checking a Batch Request Status -Sending a large batch will take some time for the server to complete. You can read a batch status using a batch id returned in the response after sending a batch. +Sending a large batch will take some time for the server to complete. You can read a batch status using the batch id returned in the response after sending a batch. + +### Sample codes + +=== "HTTP" + ```http + GET /restapi/v1.0/account/~/a2p-sms/batches/2157ac7d-baab-4d0e-1262-deada6c7xxxx + ``` === "JavaScript" ```javascript @@ -454,9 +469,9 @@ Sending a large batch will take some time for the server to complete. You can re platform.on(platform.events.loginSuccess, async function(response){ try{ - var resp = await platform.get('/restapi/v1.0/account/~/a2p-sms/batch/{batchId}') + var resp = await platform.get('/restapi/v1.0/account/~/a2p-sms/batches/2157ac7d-baab-4d0e-1262-deada6c7xxxx') var jsonObj = await resp.json() - console.log(JSON.stringify(jsonObj)) + console.log(jsonObj) }catch(e){ console.log(e.message) } @@ -471,7 +486,7 @@ Sending a large batch will take some time for the server to complete. You can re platform = sdk.platform() platform.login( "username", "extension", "password" ) - resp = platform.get('/restapi/v1.0/account/~/a2p-sms/batch/{batchId}') + resp = platform.get('/restapi/v1.0/account/~/a2p-sms/batches/2157ac7d-baab-4d0e-1262-deada6c7xxxx') print resp.text() ``` @@ -485,7 +500,7 @@ Sending a large batch will take some time for the server to complete. You can re $platform = $rcsdk->platform(); $platform->login( "username", "extension_number", "password" ); - $resp = $platform->get('/restapi/v1.0/account/~/a2p-sms/batch/{batchId}'); + $resp = $platform->get('/restapi/v1.0/account/~/a2p-sms/batches/2157ac7d-baab-4d0e-1262-deada6c7xxxx'); print_r ($resp->json()); ?> ``` @@ -508,7 +523,7 @@ Sending a large batch will take some time for the server to complete. You can re { RestClient rc = new RestClient("client_id", "client_secret", true); await rc.Authorize("username", "extension_number", "password"); - + string batchId = "2157ac7d-baab-4d0e-1262-deada6c7xxxx"; var resp = await rc.Restapi().Account().A2pSms().Batch(batchId).Get(); Console.WriteLine(JsonConvert.SerializeObject(resp)); } @@ -535,7 +550,7 @@ Sending a large batch will take some time for the server to complete. You can re public static void get_batch_result(String batchId) throws RestException, IOException{ RestClient rc = new RestClient("client_id", "client_secret", "server_url"); rc.authorize("username", "extension_number", "password"); - + String batchId = "2157ac7d-baab-4d0e-1262-deada6c7xxxx"; var resp = restClient.restapi().account().a2psms().batch(batchId).get(); String jsonStr = new Gson().toJson(resp, new TypeToken(){}.getType()); System.out.println(jsonStr); @@ -550,22 +565,25 @@ Sending a large batch will take some time for the server to complete. You can re rc = RingCentral.new( 'client_id', 'client_secret', 'server_url') rc.authorize( username: 'username', extension: 'extension_number', password: 'password') - resp = rc.get('/restapi/v1.0/account/~/a2p-sms/batch/{batchId}') + resp = rc.get('/restapi/v1.0/account/~/a2p-sms/batches/2157ac7d-baab-4d0e-1262-deada6c7xxxx') puts resp.body ``` -The code samples above would all produce a response that would appear similar to the one below. The batch's status is highlighted for you. +### Response + +The code samples above would all produce a response that would appear similar to the one below. The batch's status is highlighted. ```json hl_lines="6" { - "id": "2157ac7d-baab-4d0e-1262-deada6c757c8", + "id": "2157ac7d-baab-4d0e-1262-deada6c7xxxx", "from": "+16505550100", "batchSize": 2, - "processedCount": 0, + "processedCount": 2, "status": "Completed", "creationTime": "2020-10-12T16:50:35.033902Z", "lastModifiedTime": "2020-10-12T16:50:39.033902Z", - "rejected": [] + "rejected": [], + "cost": 0.014 } ``` diff --git a/docs/messaging/sms/sending-images.md b/docs/messaging/sms/sending-images.md index efa2fd61..bef2b554 100644 --- a/docs/messaging/sms/sending-images.md +++ b/docs/messaging/sms/sending-images.md @@ -8,39 +8,48 @@ When assembling a multipart message, it is important to remember that the root p !!! warning "Attachment Limitations" * There is a combined limit of 1.5M bytes for all attachments. - * There is a limit of 10 attachments for any request. + * There is a limit of 10 attachments for any request. === "JavaScript" ```javascript - const SDK = require('ringcentral') + const RingCentral = require('@ringcentral/sdk').SDK const FormData = require('form-data') - const rcsdk = new SDK({ + + const rcsdk = new RingCentral({ server: "server_url", appKey: "client_id", appSecret: "client_secret" }) - const platform = rcsdk.platform() - platform.login({ - username: "username", extension: "extension_number", password: "password" - }).then(response => { - const body = { - from: { phoneNumber: "username" }, - to: [ { phoneNumber: "recipient_number" } ], - text: 'Hello world' - } - const formData = new FormData() - file = {filename: 'request.json', contentType: 'application/json'}; - formData.append('json', - Buffer.from(JSON.stringify(body)), - {filename: 'request.json', contentType: 'application/json'}) - formData.append('attachment', - require('fs').createReadStream('./test.jpg')) - platform.post('/account/~/extension/~/sms', formData).then(response => { - console.log('MMS sent: ' + response.json().id) - }).catch(e => { - console.error(e) - }) - }).catch(e => { - console.error(e) - }) + + var platform = rcsdk.platform(); + + platform.login({username: "username", extension: "extension_number", password: "password"}) + + platform.on(platform.events.loginSuccess, async function(){ + send_mms() + }); + + async function send_mms(){ + var FormData = require('form-data'); + formData = new FormData(); + var body = { + from: {'phoneNumber': "user_phone_number"}, + to: [{'phoneNumber': "recipient_phone_number"}] + } + + formData.append('json', new Buffer.from(JSON.stringify(body)), { + filename: 'request.json', + contentType: 'application/json' + }); + + formData.append('attachment', require('fs').createReadStream('test.jpg')); + try { + var resp = await platform.post('/restapi/v1.0/account/~/extension/~/mms', formData) + var jsonObj = await resp.json() + console.log("MMS sent. Message status: " + jsonObj.messageStatus) + console.log('Message Id: ' + jsonObj.id) + }catch (e){ + console.log(e.message) + } + } ``` === "Python" diff --git a/mkdocs.yml b/mkdocs.yml index b39a49da..8fc7cc91 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -88,13 +88,14 @@ pages: - 'SMS and Fax': - 'Overview': 'messaging/index.md' - 'Getting Started': 'messaging/quick-start.md' - - 'SMS': + - 'Standard SMS': - 'Best Practices': 'messaging/sms/best-practices.md' - 'Sending an SMS': 'messaging/sms/sending-sms.md' - 'Sending an MMS': 'messaging/sms/sending-images.md' - 'Valid SMS Numbers': 'messaging/sms/valid-sms-numbers.md' - 'High Volume SMS': - 'Overview': 'messaging/sms/high-volume/index.md' + - 'Best Practices': 'messaging/sms/high-volume/best-practices.md' - 'Sending High Volume SMS': 'messaging/sms/high-volume/sending-highvolume-sms.md' - 'Reading High Volume Message Store': 'messaging/sms/high-volume/message-store.md' - 'Toll-Free vs. Local Numbers': 'messaging/sms/high-volume/toll-free-sms-vs-local-numbers.md'