SMS Notifications

If a user has a role and has at least one phone number set for them, they will automatically start receiving SMS notifications when they are offline.

Content of the SMS messages sent by TalkJS are customizable in our Dashboard.

You can set multiple phone numbers for your users. In case of multiple numbers for a user, TalkJS will notify all phone numbers on record. All numbers should be in the international format and start with a +. If you like to remove all phone numbers for a user, you can set their phone number field to null.

Be aware that some mobile carriers use automatic spam filters that could prevent delivery of your SMS notifications. Unfortunately, this is not something that we can disable. If you discover that users don't always receive your SMS notifications, we recommend editing your template to remove any links, and trying again. This seems to help messages avoid getting caught by the filters.

Example phone field using the JS SDK

const me = new Talk.User({
  ...
  // Setting a single number
  phone: "+12025550173",


  // Setting multiple numbers at once
  phone: ["+12025550173", "+905209876543"],


  // Removing all numbers on record
  phone: null
});

The behaviour is same with the REST API as well.

Disabling SMS Notifications

To disable SMS notifications for a user, you can remove their phone numbers. You can also mute notifications for a particular conversation (via the REST API) in which case your user won't receive any notifications for that conversation, including SMS'.

A note about SMS pricing & segmentation

SMS notifications are charged per segment. You can limit how many segments a single notification message could be in the Dashboard. Before setting the limit, it's important to understand what SMS segments are.

With the standard SMS encoding, you can only have 140 bytes in a message. A character takes 7 bits to encode and 140 bytes x 8 bits in a byte divided 7 bits means we are limited to 160 characters per segment. This limit means long messages need to be send in multiple parts, or segments, and automatically merged on the phone when they are received. This process happens all the time you send or recieve a long message on your phone.

To be able to merge these segments into one message, each message needs to start with a special header called User Data Header (UDH). This brings down the maximum character limit to 153 for each segment. So if you have a message that's exactly 160 characters, it'll be send as one segment that's 160 characters. If your message is 161 characters, then the message is split into 2 segments, first with 153 characters and second with 8 characters.

This all assumed your messages don't include any unicode characters which are found in languages such as Hindi, Turkish, Arabic, Chinese, Korean, Japanese, or Cyrillic alphabet languages. When your messages include a special character that can't be encoded with GSM, 16-bit UCS-2 encoding is used instead. With UCS-2 encoding, a segment is limited to 70 characters. Longer messages encoded with UCS-2 are also split into segments of 67 characters, with the difference used for the UDH. Since 70 characters may not be enough for most cases, TalkJS automaticlly doubles the maximum segments you picked for messages with special characters.

You can learn more about message sizes and segmentation on Wikipedia.

Opting Out of Receiving SMS Messages via Reply

In the US and Canada, we support replying via SMS to stop receiving SMS notifications per regulations.

Your users can opt out from SMS notifications by replying to the message with any of the following:

  • ARRET (French)
  • CANCEL
  • END
  • OPT-OUT
  • OPTOUT
  • QUIT
  • REMOVE
  • STOP
  • TD

Once they reply, the number they replied with won't receive any SMS notifications from TalkJS. If the user has more than one phone number, other numbers won't be affected.

In TalkJS Dashboard, we provide a way to easily add a customizable help text to the end of your messages for users in US and Canada.

Linking back to your app

Like email notifications, SMS notifications allow you to link back to your app in a variety of ways. Read how to set this up.

Be aware that some carriers will automatically reject SMS messages that include links, which is something we have no control over. If including links, check that your messages are delivered successfully, and try removing any links if you have issues.