Skip to main content

Advanced opt in/out for Messaging

Advanced Opt In / Out allows users to configure and personalise their own auto response behavior to ensure CTIA & TCPA compliance, negating the need to implement their own mechanisms in order to align with industry standards.

You can personalize your keywords and auto responses to trigger based on inbound messages from certain countries to allow for localised language support for your brand.

When an end user sends an inbound text message containing a keyword or phrase, Telnyx will automatically recognize the keyword and trigger an automated response and block rule (if applicable) that has been pre-programmed by the business or organization.

The API reference can be found here.

Default SMS/MMS auto-response behavior​

Without this feature being explicitly enabled, a default opt-out management behavior takes place on the platform.

Opt-in - The following keywords removes removes an existing block rule.

  • start
  • unstop

Opt-out - The following list of keywords initiates a block rule

  • stop
  • stopall
  • stop all
  • unsubscribe
  • cancel
  • end
  • quit

Note: Block rules take place on the messaging profile level.

Subsequent attempts to message a destination will be blocked at the API level with a 40300 error code outlined here.

The API response looks like -

{
    "errors": [
        {
            "code": "40300",
            "title": "Blocked due to STOP message",
            "detail": "Messages cannot be sent from '{TelnyxNumber}' to '{DestinationNumber}' due to an existing block rule.",
            "meta": {
                "url": "https://developers.telnyx.com/api/errors/40300"
            }
        }
    ]
}

Creating a custom opt-in/out auto response​

Here's an example of configuring a custom auto response.

Request -

curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{
      {
        "op": "start",
        "keywords": [
          "START"
        ],
        "resp_text": "You are now subscribed to receive promotional messages from bob's burgers, Reply STOP to opt-out",
        "country_code": "UK"
      }' \
  https://api.telnyx.com/v2/messaging_profiles/{profile_id}/autoresp_configs

Response -

{
  "data": {
    "op": "start",
    "keywords": ["START"],
    "resp_text": "You are now subscribed to receive promotional messages from bob's burgers, Reply STOP to opt-out",
    "country_code": "UK",
    "id": "369fba3b-db79-4403-ad50-44aabafad4fe",
    "created_at": "2023-03-24T16:22:57.147058+00:00",
    "updated_at": "2023-03-24T16:22:57.147058+00:00"
  }
}

What are the limitations of this feature which should I be aware of?​

  • START, STOP & HELP are reserved keywords for their respective operations and cannot be modified.
  • These default operations have a 20 character minimum limit for the auto response message.
  • Users can optionally make additional auto responses on a messaging profile.
  • One auto response configuration can use a maximum of 20 trigger keywords.
  • Users can optionally create additional configurations per country using the ISO 3166-1 alpha-2 format using the country_code parameter.
  • This feature is language agnostic.

Toll-free limitations​

Toll-Free numbers have a layer of opt-out handling outside of Telnyx that cannot be removed or customized. When an end user texts the word STOP to your Toll-Free number, the user will be opted-out of further messaging from your number, and will receive this auto-reply:

NETWORK MSG: You replied with the word "stop" which blocks all texts sent from this number. Text back "unstop" to receive messages again.

If the end user then sends the word START or UNSTOP, they will be opted back in to receive messaging from your number, and will receive this auto-reply:

NETWORK MSG: You have replied "unstop" and will begin receiving messages again from this number.

Notice: You will now see "You have replied "Start" ...." for START messages, and "Unstop" for UNSTOP messages. The keyword in the auto response will now match the word send in the original opt-in SMS.

How can I programmatically track opt out behavior in my application?​

By default, Telnyx automatically drops messaging content in storage after 10 days in storage. In order to allow customers to better track the default auto response types such as START, STOP or HELP messages, we've enabled an extra attribute via the inbound message webhook payload called autoresponse_type. This is also referenced in your SMS Logs via Detail Record Search Reporting.

Example payload -

{
  "data": {
    "event_type": "message.received",
    "id": "b301ed3f-1490-491f-995f-6e64e69674d4",
    "occurred_at": "2019-12-09T20:16:07.588+00:00",
    "payload": {
      "autoresponse_type": "HELP",
      "cc": [],
      "completed_at": null,
      "cost": null,
      "direction": "inbound",
      "encoding": "GSM-7",
      "errors": [],
      "from": {
        "carrier": "T-Mobile USA",
        "line_type": "long_code",
        "phone_number": "+1312500000",
        "status": "webhook_delivered"
      },
      "id": "84cca175-9755-4859-b67f-4730d7f58aa3",
      "media": [],
      "messaging_profile_id": "740572b6-099c-44a1-89b9-6c92163bc68d",
      "organization_id": "47a530f8-4362-4526-829b-bcee17fd9f7a",
      "parts": 1,
      "received_at": "2019-12-09T20:16:07.503+00:00",
      "record_type": "message",
      "sent_at": null,
      "tags": [],
      "text": "HELP",
      "to": [
        {
          "carrier": "Telnyx",
          "line_type": "Wireless",
          "phone_number": "+1773005000",
          "status": "webhook_delivered"
        }
      ],
      "type": "SMS",
      "valid_until": null,
      "webhook_failover_url": null,
      "webhook_url": "http://webhook.site/04bbd2e3-09b5-4c9e-95de-a1debeb9e675"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "http://webhook.site/04bbd2e3-09b5-4c9e-95de-a1debeb9e675"
  }
}

On this page​