tutorials/SMSMessaging.md in cpaas-sdk-1.1.0 vs tutorials/SMSMessaging.md in cpaas-sdk-1.2.0

- old
+ new

@@ -13,20 +13,20 @@ }) ``` Before moving to how the response body looks, let's walk through the highlights on the SMS request: + `sender_address` indicates which DID number that user desires to send the SMS from. It is expected to be an E.164 formatted number. - + If `sender_address` field contains `default` keyword, $KANDY$ discovers the default assigned SMS DID number for that user and utilizes it as the sender address. + + If `sender_address` field contains `default` keyword, $KANDY$ discovers the default assigned SMS DID number for that user or project and utilizes it as the sender address. + `destination_address` can either be an array of phone numbers or a single phone number string within the params containing the destinations that corresponding SMS message will be sent. For SDK v1, only one destination is supported on $KANDY$. + Address value needs to contain a phone number, ideally in E.164 format. Some valid formats are: - +16131234567 - tel:+16131234567 - sip:+16131234567@domain - sip:6131234567@domain + `message` field contains the text message in `UTF-8` encoded format. -> The number provided in `sender_address` field should be purchased by the account and assigned to the project, otherwise $KANDY$ replies back with a Forbidden error. +> The number provided in `sender_address` field should be purchased by the account and assigned to the project or user, otherwise $KANDY$ replies back with a Forbidden error. Now, let's check the successful response: ```ruby { @@ -57,12 +57,12 @@ type: Cpaas::Conversation.types[:SMS], webhook_url: 'https://myapp.com/inbound-sms/webhook', destination_address: '+16139998877' }) ``` -+ `destination_address` is an optional parameter to indicate which SMS DID number has been desired to receive SMS messages. Corresponding number should be one of the assigned/purchased numbers of the project, otherwise $KANDY$ replies back with Forbidden error. Also not providing this parameter triggers $KANDY$ to use the default assigned DID number against this user, in which case the response message for the subscription contains the `destination_address` field. It is highly recommended to provide `destination_address` parameter. -+ `webhook_url` is a webhook that is present in your application which is accessible from the public web. The sms notifications would be delivered to the webhook and the received notification can be consumed by using the `Cpaas::Notification.parse` helper method. The usage of `Cpaas::Notification.parse` is explained in Step 2. ++ `destination_address` is an optional parameter to indicate which SMS DID number has been desired to receive SMS messages. Corresponding number should be one of the assigned/purchased numbers of the project or user, otherwise $KANDY$ replies back with Forbidden error. Also not providing this parameter triggers $KANDY$ to use the default assigned DID number against this project or user, in which case the response message for the subscription contains the `destination_address` field. It is highly recommended to provide `destination_address` parameter. ++ `webhook_url` is a webhook endpoint that is present in your application server which is accessible from the public web. The sms notifications would be delivered to this webhook endpoint and the received notification can be consumed by using the `Cpaas::Notification.parse` helper method. The usage of `Cpaas::Notification.parse` is explained in Step 2. A successful subscription would return: ```ruby { webhook_url: 'https://myapp.com/inbound-sms/webhook', @@ -70,18 +70,21 @@ subscription_id: '544f12a3-123ad5e-b169' } ``` > + For every number required to receive incoming SMS, there should be an individual subscription. -> + When a number has been unassigned from a project, all corresponding inbound SMS subscriptions are cancelled and `sms_subscription_cancellation_notification` notification is sent. +> + When a number has been unassigned from a project or user, all corresponding inbound SMS subscriptions are cancelled and `sms_subscription_cancellation_notification` notification is sent. -Now, you are ready to receive inbound SMS messages via webhook, for example - 'https://myapp.com/inbound-sms/webhook'. +Now, you are ready to receive inbound SMS messages via webhook endpoint, for example - 'https://myapp.com/inbound-sms/webhook'. For more information about webhook and subscription, you can refer the [SMS starter app](https://github.com/Kandy-IO/kandy-cpaas-ruby-sdk/tree/v1.2.0/examples/sms). ### Step 2: Receiving notification -An inbound SMS notification via webhook can be parsed by using the `Cpaas::Notification.parse` method: +An inbound SMS notification received by your webhook endpoint can be parsed by using the `Cpaas::Notification.parse` method: ```ruby + # This is a sample representation of the method present in your application server + # that receives request when the particular webhook endpoint (passed as webhook_url) + # is hit by the CPaaS server with a notification as the request's body. def webhook(inbound_notification) parsed_Response = Cpaas::Notification.parse(inbound_notification) end ``` The parsed response returned from the `Cpaas::Notification.parse` method can look like this: @@ -100,10 +103,13 @@ ## Real-time outbound SMS sync $KANDY$ provides notification for outbound SMS messages, to sync all online clients up-to-date in real time. The outbound notification received can also be parsed by using the `Cpaas::Notification.parse` method: ```ruby + # This is a sample representation of the method present in your application server + # that receives request when the particular webhook endpoint (passed as webhook_url) + # is hit by the CPaaS server with a notification as the request's body. def webhook(outbound_notification) parsed_response = Cpaas::Notification.parse(outbound_notification) end ``` The parsed response returned from the `Cpaas::Notification.parse` method can look like this: @@ -124,8 +130,10 @@ > In order to receive this notification, user should have inbound SMS subscription. Obviously this notification cannot be provided when only send SMS has been used without an SMS related subscription. > For trial users, maximum number of SMS messages stored is 1000. When new messages are inserted to history, oldest ones are being removed. +## Example +To learn more, check the [SMS starter app](https://github.com/Kandy-IO/kandy-cpaas-ruby-sdk/tree/v1.2.0/examples/sms). ## References -For all SMS related method details, refer to [SMS](/developer/references/ruby/1.0.0#sms-send). +For all SMS related method details, refer to [SMS](/developer/references/ruby/1.2.0#sms-send).