Skip to main content
Advanced Opt-In/Out lets you customize keyword triggers and auto-responses on your messaging profile. Configure country-specific responses, custom keywords, and track opt-out behavior via webhooks — all while maintaining CTIA & TCPA compliance.

​
Default behavior

Without custom configuration, Telnyx handles standard opt-in/out keywords automatically:
These keywords create a block rule preventing further messages to the recipient:
KeywordAction
STOPBlock messages
STOPALLBlock messages
STOP ALLBlock messages
UNSUBSCRIBEBlock messages
CANCELBlock messages
ENDBlock messages
QUITBlock messages
Block rules operate at the messaging profile level. If a user opts out from one number on your profile, they’re opted out from all numbers on that profile.
When you attempt to message a blocked recipient, the API returns: 
{
  "errors": [
    {
      "code": "40300",
      "title": "Blocked due to STOP message",
      "detail": "Messages cannot be sent from '{from}' to '{to}' due to an existing block rule."
    }
  ]
}

​
Create custom auto-responses

Configure custom keyword responses for opt-in, opt-out, and help messages: 
# Create a custom opt-in auto-response
curl -X POST \
  https://api.telnyx.com/v2/messaging_profiles/{profile_id}/autoresp_configs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "op": "start",
    "keywords": ["JOIN", "SUBSCRIBE", "YES"],
    "resp_text": "Welcome to Acme alerts! You'\''ll receive up to 4 msgs/month. Reply HELP for help, STOP to cancel. Msg&data rates may apply.",
    "country_code": "US"
  }'

# Create a custom HELP response
curl -X POST \
  https://api.telnyx.com/v2/messaging_profiles/{profile_id}/autoresp_configs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "op": "help",
    "keywords": ["HELP", "INFO"],
    "resp_text": "Acme Corp: For support call 1-800-555-0123 or email help@acme.com. Reply STOP to opt out. Msg&data rates may apply.",
    "country_code": "US"
  }'

# Create a custom opt-out response
curl -X POST \
  https://api.telnyx.com/v2/messaging_profiles/{profile_id}/autoresp_configs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "op": "stop",
    "keywords": ["STOP", "QUIT", "CANCEL"],
    "resp_text": "You have been unsubscribed from Acme alerts. Reply START to resubscribe.",
    "country_code": "US"
  }'

​
Operation types

Operation (op)PurposeDefault keywords
startOpt-in — removes block ruleSTART, UNSTOP
stopOpt-out — creates block ruleSTOP, STOPALL, UNSUBSCRIBE, CANCEL, END, QUIT
helpHelp — sends info responseHELP
CustomAny custom keyword response(none)

​
Country-specific auto-responses

Configure different responses per country using ISO 3166-1 alpha-2 codes. This enables localized language support: 
# English (US)
curl -X POST \
  https://api.telnyx.com/v2/messaging_profiles/{profile_id}/autoresp_configs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "op": "stop",
    "keywords": ["STOP"],
    "resp_text": "You have been unsubscribed. Reply START to resubscribe.",
    "country_code": "US"
  }'

# Spanish (Mexico)
curl -X POST \
  https://api.telnyx.com/v2/messaging_profiles/{profile_id}/autoresp_configs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "op": "stop",
    "keywords": ["PARAR", "DETENER"],
    "resp_text": "Te has dado de baja. Responde INICIO para volver a suscribirte.",
    "country_code": "MX"
  }'

# French (Canada)
curl -X POST \
  https://api.telnyx.com/v2/messaging_profiles/{profile_id}/autoresp_configs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "op": "stop",
    "keywords": ["ARRET", "ARRETER"],
    "resp_text": "Vous êtes désabonné. Répondez DEBUT pour vous réabonner.",
    "country_code": "CA"
  }'

# UK English
curl -X POST \
  https://api.telnyx.com/v2/messaging_profiles/{profile_id}/autoresp_configs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "op": "start",
    "keywords": ["START"],
    "resp_text": "You are now subscribed to receive messages from Acme. Reply STOP to opt out.",
    "country_code": "GB"
  }'
The feature is language agnostic — you can use keywords and responses in any language. The country_code field determines which auto-response applies based on the sender’s number origin.

​
Track opt-out behavior via webhooks

When a user sends an opt-in, opt-out, or help keyword, the inbound message webhook includes an autoresponse_type field: 
{
  "data": {
    "event_type": "message.received",
    "payload": {
      "autoresponse_type": "STOP",
      "from": {
        "phone_number": "+15559876543"
      },
      "text": "STOP",
      "to": [
        {
          "phone_number": "+15551234567"
        }
      ]
    }
  }
}

​
Handle opt-out webhooks

from flask import Flask, request, jsonify

app = Flask(__name__)


@app.route("/webhooks/messaging", methods=["POST"])
def handle_webhook():
    data = request.json["data"]

    if data["event_type"] != "message.received":
        return jsonify({"status": "ignored"}), 200

    payload = data["payload"]
    autoresponse_type = payload.get("autoresponse_type")
    phone = payload["from"]["phone_number"]

    if autoresponse_type == "STOP":
        # User opted out — update your database
        db.execute(
            "UPDATE subscribers SET opted_out = TRUE, opted_out_at = NOW() "
            "WHERE phone = %s",
            (phone,),
        )
        print(f"User {phone} opted out")

    elif autoresponse_type == "START":
        # User opted back in
        db.execute(
            "UPDATE subscribers SET opted_out = FALSE "
            "WHERE phone = %s",
            (phone,),
        )
        print(f"User {phone} opted back in")

    elif autoresponse_type == "HELP":
        # User requested help — log for support
        print(f"User {phone} requested help")

    return jsonify({"status": "ok"}), 200
The autoresponse_type field is also available in your SMS Logs via Detail Record Search reporting.

​
Limitations

START, STOP, and HELP are reserved keywords for their respective operations and cannot be reassigned to different operations. You can add additional keywords to each operation, but the defaults always remain active.
Default operations (start, stop, help) require a minimum 20 characters for the auto-response message. This ensures compliance with carrier requirements.
Each auto-response configuration supports a maximum of 20 trigger keywords.
Toll-free numbers have a separate carrier-level opt-out system that Telnyx cannot customize or remove. When a user texts STOP to a toll-free number:
  1. The carrier sends its own 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.
  1. Your custom STOP response is also sent (if configured)
  2. The carrier block is applied independently of Telnyx’s block rule
When a user texts START or UNSTOP:
NETWORK MSG: You have replied “unstop” and will begin receiving messages again from this number.
You cannot prevent the carrier’s NETWORK MSG responses on toll-free numbers. Design your custom responses to complement (not contradict) these messages.
Block rules apply at the messaging profile level, not the individual number level. If a user opts out from any number on your profile, they’re blocked from all numbers on that profile.To manage separate opt-out lists for different programs, use separate messaging profiles.

Messaging Profiles

Configure the messaging profile that manages your opt-in/out rules.

Webhooks

Set up webhooks to receive opt-in/out events.

Short Codes

Short code keyword handling and carrier certification.

Toll-Free Verification

Toll-free number verification and compliance.