​

Enable and Operate the SMS Double Opt-In Flow

​

1. When to enable it

• US and Canadian marketing traffic. The CTIA Short Code Monitoring Handbook (§5.1.3 and §5.2) grades short code and 10DLC campaigns on verified affirmative consent: a recorded prompt followed by a recorded affirmative reply. Carriers reviewing campaign attestations expect to see exactly that pattern, and short code programs are monitored most closely.
• Launches headed for campaign review. A prompt plus a recorded reply is stronger opt-in evidence than a bare web-form capture, and it is the evidence tier 10DLC and short code reviews ask for.

• Most of the EU/UK under GDPR, where legitimate interest or an existing soft opt-in exception covers the send.
• Australia under the Spam Act, where a prior business relationship plus a working unsubscribe path suffices.
• Any audience where consent you already hold (imported or collected at signup) satisfies the local regime; see Country Requirements for per-jurisdiction posture.

​

2. The consent state machine

• No record is simply the absence of a consent row for the pair.
• Pending is a row with consent type sms_double_opt_in stamped awaiting_yes at prompt time. It records that the contact was prompted; it is not a grant, and while it is the pair’s only row, marketing stays held.
• Confirmed is an opted_in grant row written when the reply arrives. The original prompt row stays in the ledger, stamped confirmed, so the pair carries two dated events: prompted at, and confirmed at.

​

3. Enable it

​

From the dashboard

​

From the API

curl -X PUT https://api.orbit.devotel.io/api/v1/settings/general \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {
      "sms_double_opt_in": {
        "enabled": true,
        "brand_name": "Acme",
        "help_contact": "help@acme.com"
      }
    }
  }'

• enabled must be the literal boolean true. The string "true" leaves the flow off, because the gate checks strict equality.
• The settings merge replaces the whole sms_double_opt_in object, so send all three keys every time; sending only enabled clears your branding.

​

4. The confirmation prompt, and customizing it

Reply YES to subscribe to Acme alerts. Msg & data rates may apply. Msg freq varies. Reply STOP to opt out. Help: help@acme.com.

• brand_name replaces the generic service reference. Keep it at or under 32 characters.
• help_contact appends the Help: sentence when the branded body still fits one SMS segment (160 GSM-7 characters). If your branding pushes the body over one segment, the prompt falls back to a shorter unbranded body so the rates disclosure and STOP instruction are never dropped.

​

5. While pending: marketing sends are held, not failed

• The send returns the message with status: "skipped" and reason: "pending_consent". This is a soft skip in the same family as quiet-hours and suppression skips, not the 422 an opted-out recipient produces; batch and campaign jobs continue past the contact.
• Campaign reports show the recipient as skipped with that reason: not delivered, not failed. A held send is not billed as a delivered message.
• Because the message never reaches a carrier, no delivery webhook follows it. The skipped result is the whole record of the attempt, so do not build alerting that treats pending_consent as a delivery failure; it is the flow working as designed.

​

6. Inbound YES: how the reply unblocks the contact

​

7. Audit: reading the evidence back

• Per contact: open Audience → Contacts → the contact → Consent log. You see the pending prompt row (prompted-at, and the send that triggered it) and the opted_in grant (confirmed-at, source of the reply) as separate entries.
• Tenant-wide: the Consent ledger lists grants and their states, including the Expiring view for time-bounded grants.
• Exports: the consent export gives you ledger rows over a window; use it to show that for any marketed contact, a prompt event precedes the grant event. See Consent Management.
• Evidence packages: the evidence binder assembles consent history with the rest of your compliance evidence for a regulator or carrier discovery request. See Evidence Binder.

​

8. Common failure modes

​

Worked example: US marketing tenant, end to end

1. In Settings → Compliance → SMS double opt-in: switch on, brand name Acme Runs, help contact help@acmeruns.com, save. (The PUT /settings/general call from §3 does the same.)
2. The campaign sends a marketing SMS to +14155550101, a contact with no consent record. The send is rewritten: the contact receives Reply YES to subscribe to Acme Runs alerts. Msg & data rates may apply. Msg freq varies. Reply STOP to opt out. Help: help@acmeruns.com. and the contact’s Consent log gains a pending row.
3. A second campaign fires before the contact answers. That recipient’s result is status: "skipped", reason: "pending_consent"; everyone else in the audience receives the campaign.
4. The contact texts Yes. Inbound keyword handling writes the opted_in grant and stamps the pending row confirmed; the Consent log now shows both dated events.
5. The next campaign delivers the real creative to that contact.

​

Related

• Confirmed Consent (Double Opt-In) Handshakes
• Consent Management
• Migrating Consent
• Evidence Binder
• Opt-Out & Suppression Lists