Manage incoming SMS with webhooks

Using webhooks to manage incoming SMS related to jobs

You can use webhooks to route incoming SMS messages sent from your customers or resources in the field.

For example, you might want to send a survey at the end of a job to the customer to rate their experience and have their responding SMS update the job with their feedback.

Alternatively, you might want a resource to be able to check in to start a job by sending an SMS to a number assigned to your organization.

Incoming SMS numbers must be obtained through Skedulo to ensure that it is able to communicate with our internal endpoints and that your incoming messages are able to be routed correctly.

Skedulo will purchase a number for your organization through Twilio and preconfigure it for use as your specific number for inbound SMS.

To request an incoming SMS number, contact your Skedulo Customer Success representative.

Create an inbound SMS webhook

This example uses ngrok for demonstration purposes only. It is assumed that you have your own server infrastructure that you can configure to receive webhook responses.

  1. Start your server and confirm the HTTPS address. Only secure HTTPS URLs are accepted for Skedulo webhooks. See the Use webhooks section for more information about setting up webhooks for Skedulo.

  2. Use the following request body to create a webhook called inbound_sms:

{
  "name": "inbound_sms",
  "url": "https://ea8d656e.ngrok.io",
  "type": "inbound_sms"
}

The success response confirms the webhook id:

{
  "result": {
    "id": "fb9abd73-26d4-42f2-a5f7-e5c153a20440",
    "name": "inbound_sms",
    "url": "https://ea8d656e.ngrok.io",
    "headers": {},
    "type": "inbound_sms"
  }
}

  1. Request an SMS number from Skedulo that is configured as an inbound SMS number for your tenant ID.

    When an inbound SMS is sent to that number, the webhook receives the following information, with the contents of the SMS shown in the body:

{
    "key": {
        "id": "message_sid_001",
        "vendor": "twilio"
    },
    "to": "+61411123456",
    "from": "+61411222333",
    "body": "msg body 1 a",
    "receivedAt": "2019-09-24T05:57:49.323Z"
}

  1. Delete the webhook by sending a DELETE request to the /webhooks endpoint referencing the webhook id.

    For more information about deleting webhooks, see the Establishing webhooks section.