Sending and Recieving SMS Messages

BioT allows sending and receiving SMS messages to and from users with valid registered phone numbers. This enables sending SMS notifications, receiving user replies, and taking appropriate actions based on them.

An example use case would be sending reminders to patients to take their medication, followed by a request for confirmation by replying with the digit '1' upon taking the medication. This reply will be passed to a BioT plugin, which will record it in the database and reflect in the organization portal that this specific user has taken their medication on time.

Sending SMS Messages

To send an SMS message make a request to the following API:

POST https://example.com/notification/v1/sms/send

With the request body:

{
    "message": "This is a reminder to take your medication. Please reply by sending the message "Medication Taken" once you have taken it.",
    "phoneNumber": "+1555XXXXXXX"
}

And the response:

{
  "messageId": "d53ffc75-e067-424c-b572-d32e4fc4a244"
}

The messageIdis the unique message ID of the sent SMS message. Please save it for future reference if you need to identify the message the user is replying to.

Please note:

• Phone numbers must be entered in full format.
• The message length and characters are limited by the receiving device. This means that the message may appear garbled or be split into multiple messages if the device cannot display non-English characters or has a limited message length.
• In some countries, charges may apply to the message recipient.

Receiving SMS Messages

While sending SMS is available worldwide, receiving SMS messages is available in a limited number of countries.
At the time of writing this article the supported countries are:
Australia (except Sydney region), Austria, Belgium, Brazil, Bulgaria, Canada, Chile, China, Colombia, Cook Islands, Czech Republic, Denmark, Dominican Republic, Ecuador, Egypt, Estonia, Finland, France, Germany, Guam, Hong Kong, Hungary, India, Ireland, Israel, Italy, Japan, Jersey, Lithuania, Luxembourg, Malaysia, Mexico, Morocco, Myanmar, Netherlands, New Zealand, Norway, Peru, Philippines, Poland, Portugal, Puerto Rico, Romania, Russia, Singapore, Somalia, South Africa, Spain, Sweden, Taiwan, Thailand, Ukraine, UAE, UK, USA, Uruguay, Virgin Islands

When you opt for this service, BioT will assign a static local number for the country.
Please get in touch with us to assign a number of if your country is not listed above.

Register an SMS Handler Plugin

To handle SMS replies, you need to register an SMS handler plugin for the _incomingSms action under the patient, organization-user, or caregiver entities.
For more information on creating and registering plugins for notifications click here.

SMS Handling

When a user replies to an SMS message, they will respond to the designated static number. BioT then attempts to retrieve the user's details from the database by searching for the phone number associated with the response.
BioT will then invoke the SMS handler plugin and send a message with the sender entity details and the SMS message message details.
For example:

{
  "metadata": {
    "entityTypeName": "patient",
    "actionName": "_incomingSms",
    "status": "SUCCESS",
    "startTime": "2023-11-25T12:27:47.279660728Z",
    "endTime": "2023-11-25T12:27:47.279662788Z",
    "traceId": "00-6561e8428d0552c950610c67645962f2-50610c67645962f2-00",
    "initiator": {
      "subject": {
        "id": "+125XXXXXXXX"
      },
      "sourceIpAddress": null
    }
  },
  "data": {
    "entity":  {
      "_name": {
          "firstName": "Patient",
          "lastName": "Zero"
      },
      "_description": "patient",
      "_email": "[email protected]",
      "_phone": "+125XXXXXXXX",
      "_locale": "en-us",
      "_gender": "MALE",
      "_dateOfBirth": "1985-11-11",
      "_address": {
          "countryCode": "US",
          "state": null,
          "city": null,
          "zipCode": null,
          "address1": null,
          "address2": null
      },
      "_mfa": {
          "enabled": false,
          "expirationInMinutes": null
      },
      "_nationalId": "76986",
      "_id": "a48b0bfe-d795-4f6a-9a28-39d2df5d8c26",
      "_ownerOrganization": {
          "id": "620e80c8-9e33-4fb8-aa38-7fe0d1d5683a",
          "name": "Demo Org",
          "templateId": "2aaa71cf-8a10-4253-9576-6fd160a85b2d",
          "parentEntityId": null
      },
      "_creationTime": "2023-11-28T14:24:31.4Z",
      "_lastModifiedTime": "2023-11-28T14:24:31.4Z",
      "_invitationAccepted": true,
      "_template": {
          "id": "a38f32d7-de6c-4252-9061-9bcdc253f6c9",
          "name": "user",
          "displayName": "User"
      },
      "_referencers": {
          "My Device": {
              "name": "My Device",
              "displayName": "My Device",
              "count": 1,
              "attributeId": "5ca2ee0a-5153-4364-8f09-42bca2a2949f",
              "templateId": "0acb3d5b-c70b-4101-b8f7-be17c452fbc5",
              "referrer": {
                  "id": "demo-device",
                  "name": "demo-device",
                  "parentEntityId": null
              }
          }
      },
      "sex": "male",
      "group": null,
      "_enabled": "ENABLED",
      "_username": "[email protected]",
      "_registrationSource": "INVITATION",
      "_canLogin": true,
      "_caption": "Zero Patient (76986)"
  },
    "additionalData": {
      "metadata": {
        "originationNumber": "+125XXXXXXXX",
        "destinationNumber": "+125XXXXXXXX",
        "messageBody": "Medication Taken",
        "inboundMessageId": "b3450bd6-3f2d-442a-8d46-221a87db25f7",
        "previousPublishedMessageId": "tfo5od7f19978unpfueng0dhspnfnltkccjbpc00"
      }
    }
  },
  "jwt": "eyJhbGciOiJSUzUxMiJ9..."
}

Important parameters:

📘

Note

For this flow to function properly, only one user can possess the sender phone number. If no users are found or multiple users have the assigned phone number, the process will fail.