> For the complete documentation index, see [llms.txt](https://docs.concurrence.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.concurrence.com/developer-guide/reference-guides/launch-sms-outreach-campaign.md).

# Launch an SMS Outreach Campaign

Send SMS with an approved Channel Manager sender, read delivery status, receive signed replies, and verify opt-out before a campaign launch.

Use this guide when your SMS sender is approved, a number is assigned, and your own backend sends the messages. Send a controlled message, read delivery status, receive a signed reply, and test opt-out before your campaign. If you still need a business profile, registration, or a number, start with [one-time provisioning](https://docs.concurrence.com/developer-guide/reference-guides/integrate-channel-manager.md).

## What You Need

Concurrence delivers these values through a secure channel. Keep the client secret, access tokens, and the webhook signing secret in your secret store and out of tickets, chat, and source control. The setup and use case IDs are not credentials, and you can quote them in an approved support channel.

* Your assigned API host.
* The setup ID and the SMS use case ID.
* The sender approval status: a verified campaign for a US long code, or an approved toll-free verification.
* A runtime client ID and secret, and the scopes granted to that client.
* The webhook signing secret for the use case.
* Your Concurrence support contacts.

You provide a public HTTPS receiver URL that your team owns, consent evidence for each recipient, approved message content that matches the registered campaign, and a phone your team controls for testing.

## 1. Get a Token and Confirm the Sender

Set `CHANNEL_SETUP_ID` and `CHANNEL_USE_CASE_ID` from your handoff. Load `CHANNEL_CLIENT_ID`, `CHANNEL_CLIENT_SECRET`, and `CHANNEL_WEBHOOK_SECRET` from your secret store. Export these variables in your test shell.

The examples use Bash, cURL, and `jq`. The token lasts one hour. Request a new one with the same call when it expires.

```bash
export CHANNEL_API_BASE=https://channels.api-us.concurrence.com

token_json=$(curl --fail-with-body --silent --show-error --config - \
  --request POST "$CHANNEL_API_BASE/v1/oauth/token" \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'scope=use-case:read sms:read sms:send sms:consent:read sms:consent:write' <<EOF
user = "$CHANNEL_CLIENT_ID:$CHANNEL_CLIENT_SECRET"
EOF
)
CHANNEL_ACCESS_TOKEN=$(jq -er '.access_token' <<<"$token_json")
export CHANNEL_ACCESS_TOKEN
jq '{token_type, expires_in, scope}' <<<"$token_json"
unset token_json

cm() { curl --fail-with-body --silent --show-error \
  --config <(printf 'header = "Authorization: Bearer %s"\n' "$CHANNEL_ACCESS_TOKEN") "$@"; }

cm "$CHANNEL_API_BASE/v1/use-case/$CHANNEL_USE_CASE_ID" |
  jq '{channel, twilio_setup_id, phone_numbers, webhook_url}'
```

The printed `scope` lists what was granted. A scope missing from it needs a corrected grant from your Concurrence contact. Confirm that `channel` is `sms`, `twilio_setup_id` is your setup ID, `phone_numbers` holds your number, and `webhook_url` is your receiver. On the token request, a `401` means the credentials are missing and a `403` means they are invalid.

## 2. Send One Controlled Message

Collect and retain recipient consent before sending either message.

Set `CHANNEL_TEST_RECIPIENT` to the phone your team controls and `CHANNEL_TEST_MESSAGE` to approved content with no personal data. The first call sends the registered opt-in message, which US long-code and US and Canada toll-free senders require before any other message. When an opt-in-message record already exists for this recipient on the use case, a repeated call returns success and sends nothing. For a recipient with an active setup-wide opt-out, the call returns `409`.

```bash
: "${CHANNEL_TEST_RECIPIENT:?set a phone your team controls}"
: "${CHANNEL_TEST_MESSAGE:?set approved test content}"

cm --request POST "$CHANNEL_API_BASE/v1/sms/opt-in" \
  --header 'Content-Type: application/json' \
  --data "{\"use_case_id\": \"$CHANNEL_USE_CASE_ID\", \"to_phone_number\": \"$CHANNEL_TEST_RECIPIENT\"}"

CHANNEL_MESSAGE_ID=$(cm --request POST "$CHANNEL_API_BASE/v1/sms/" \
  --form-string "use_case_id=$CHANNEL_USE_CASE_ID" \
  --form-string "to_phone_number=$CHANNEL_TEST_RECIPIENT" \
  --form-string "message=$CHANNEL_TEST_MESSAGE" | jq -er '.id')
```

A `201` with an `id` means the message was accepted. It does not show delivery or sender approval. A `422` explains the refusal, such as content that does not match the registered campaign, a missing opt-in message, or an opted-out recipient.

Run the send once. The request has no idempotency key, so if no response arrives, [reconcile the attempt](https://docs.concurrence.com/developer-guide/reference-guides/reconcile-channel-manager.md) before you send again.

## 3. Read Delivery

Channel Manager does not post delivery status to your receiver. Read the message, then repeat the read at a fixed interval for a bounded period, for example one read a minute for ten minutes. `sent` is an intermediate status. Stop when `status` is `delivered`, `failed`, or `undelivered`, or when the period ends. Do not poll in a tight or unbounded loop.

```bash
cm "$CHANNEL_API_BASE/v1/sms/$CHANNEL_MESSAGE_ID" |
  jq '{status, handed_off_at, delivered_at, errored_at, error_message}'
```

`status` is `pending`, `sent`, `delivered`, `failed`, or `undelivered`. Delivery confirmation depends on the carrier and can be absent, so a message can stay at `sent`. Record that outcome as unknown, not as delivered or failed. Confirm receipt on the test phone as well.

## 4. Receive Replies

Reply from the test phone. Channel Manager posts each reply to your `webhook_url`, signed with the use case secret. A reply is not a delivery receipt, and its `parent_outbound_ref` is empty, so match it to your workflow by `caller_ref` and your own records.

<details>

<summary>Minimal Python receiver for a controlled test</summary>

Run this local receiver behind your HTTPS endpoint. It limits the body size, verifies the signature over the raw body, rejects malformed requests, and stores each event once before returning success.

```python
import hashlib
import hmac
import json
import os
import sqlite3
from http.server import BaseHTTPRequestHandler, HTTPServer

SECRETS = {os.environ["CHANNEL_USE_CASE_ID"]: os.environ["CHANNEL_WEBHOOK_SECRET"]}
HEADER = "X-AMIGO-CHANNEL-MANAGER-WEBHOOK-SIGNATURE"
MAX_BODY_BYTES = 1_000_000
MANDATORY = ("use_case_id", "idempotency_key")

db = sqlite3.connect(os.environ.get("INBOUND_DB", "inbound.db"))
db.execute("CREATE TABLE IF NOT EXISTS inbound (use_case_id TEXT, idempotency_key TEXT,"
           " body BLOB, PRIMARY KEY (use_case_id, idempotency_key))")


def signed_use_cases(raw, headers):
    """Return the configured use cases whose secret signs these exact bytes."""
    received = []
    for header in headers:
        for value in header.split(","):  # rotation can send two signatures
            received.append(value.strip().encode())
    matched = set()
    for use_case_id, secret in SECRETS.items():
        expected = hmac.new(secret.encode(), raw, hashlib.sha256).hexdigest().encode()
        for value in received:
            if hmac.compare_digest(expected, value):
                matched.add(use_case_id)
    return matched


def parse_event(raw):
    """Return the event, or None when it is malformed."""
    try:
        event = json.loads(raw)
    except ValueError:
        return None
    if not isinstance(event, dict):
        return None
    for field in MANDATORY:
        if not isinstance(event.get(field), str) or not event[field]:
            return None
    return event


def receive(raw, headers):
    """Return the HTTP status for one request."""
    matched = signed_use_cases(raw, headers)
    if not matched:
        return 401
    event = parse_event(raw)
    if event is None:
        return 400
    if event["use_case_id"] not in matched:
        return 403
    with db:  # commit before acknowledging
        db.execute("INSERT OR IGNORE INTO inbound VALUES (?, ?, ?)",
                   (event["use_case_id"], event["idempotency_key"], raw))
    return 204


class Receiver(BaseHTTPRequestHandler):
    def do_POST(self):
        try:
            length = int(self.headers.get("Content-Length", ""))
        except ValueError:
            length = -1
        if length < 0:
            status = 411
        elif length > MAX_BODY_BYTES:
            status = 413
        else:
            status = receive(self.rfile.read(length), self.headers.get_all(HEADER, []))
        self.send_response(status)
        self.end_headers()


if __name__ == "__main__":
    HTTPServer(("127.0.0.1", 8080), Receiver).serve_forever()
```

Use it to test with the phone your team controls, and process stored events in a separate worker. An event can arrive more than once, and the primary key keeps one copy. A production receiver also needs your own TLS termination, timeouts, concurrency, monitoring, secret rotation, and a managed durable store.

</details>

A sender's phone number does not verify who is texting, so confirm identity in your own application before you share account details.

## 5. Validate Opt-Out

Text the exact word `STOP` from the test phone. The keyword is handled for you and is not posted to your receiver. On a toll-free sender, `HELP` is posted as a normal message. Then check three results:

1. `cm "$CHANNEL_API_BASE/v1/sms/opt-out?setup_id=$CHANNEL_SETUP_ID"` lists the test number.
2. Repeating the send in step 2 returns `422`.
3. Repeating the opt-in call returns `409`.

The opt-out covers every use case on the setup. To restore the test phone, see [SMS recipient opt-in and opt-out](https://docs.concurrence.com/developer-guide/platform-api/conversations/channel-manager.md#sms-recipient-opt-in-and-opt-out).

## 6. Record Go-Live Acceptance

The API does not enforce this record. Complete it with your team before the first production send.

* Sender approval, taken from your handoff or a status read, with the date checked.
* The controlled message ID, the last `status` you read with the time of that read, and receipt on the test phone. Record an unknown delivery outcome when no confirmation arrived.
* One stored reply, a replay that stored nothing new, and a bad signature that was refused.
* The opt-out results from step 5.
* The owner of consent evidence and approved content.
* The owner who investigates an unknown send outcome before any resend.
* Your support contacts and the setup, use case, and message IDs to quote in an approved support channel, without credentials or sensitive message content.

Unset `CHANNEL_ACCESS_TOKEN` and `CHANNEL_CLIENT_SECRET` when you finish.

## Next Steps

* [Measure response rate, time to first response, opt-out rate, and business outcomes](https://docs.concurrence.com/developer-guide/reference-guides/integrate-channel-manager.md#measure-an-sms-outreach-campaign).
* [Channel Manager reference](https://docs.concurrence.com/developer-guide/platform-api/conversations/channel-manager.md) for every SMS operation.
* [Test a Managed SMS Workflow](https://docs.concurrence.com/developer-guide/guides/test-managed-sms.md) applies when a Concurrence agent in a workspace sends the messages instead of your backend.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.concurrence.com/developer-guide/reference-guides/launch-sms-outreach-campaign.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
