Receiving SMS

Every number of your organization receives messages. Each one has a receiving environment, a live environment chosen on the dashboard's organization SMS page: replies to the number are stored there, fire an sms.received webhook to its endpoints, and can be read with its keys. A number without one drops its replies (STOP and START still apply).

const event = await verifyWebhook(await request.text(), request.headers, secret);
if (event.type === "sms.received" && event.data.received_sms_id) {
  const { data: reply } = await coss.sms.received.get(event.data.received_sms_id);
  console.log(reply?.from, reply?.to, reply?.body, reply?.keyword);
}

Webhook payloads name the message (received_sms_id), who sent it (from) and which of your numbers received it (to), never the text. List received messages, newest first, by sender or by number:

const { data: replies } = await coss.sms.received.list({ to: "+14155550123", limit: 50 });

The text comes from whoever sent it: treat it as untrusted input. Received messages are kept for 30 days, and billed per segment at the receiving number's country's rate (pricing); dropped ones aren't billed.

STOP, START and HELP

A message that is only a keyword (any case, surrounding spaces ignored) changes who you can send to. "Stop texting me" is not a keyword.

The confirmations carriers require ("You have been unsubscribed…") are sent automatically by coss.com's SMS provider. Opt-outs apply to every live environment, because your numbers are shared by all of them, whether or not the number has a receiving environment. Each environment whose list changed gets an sms.opted_out or sms.opted_in webhook; its received_sms_id is null when the message was dropped. The received message itself has its keyword.

A sender that replied STOP can't be reached from your numbers until they reply START, even if you remove the suppression entry: the carrier refuses the message (opted_out).

Opt-outs and reputation

coss.com measures, per organization over a rolling window, the share of numbers that opted out and of messages carriers filtered. High rates lead to a warning, and then to a suspension of live sending, as for email bounces and complaints: see the Acceptable Use Policy for the thresholds. Send only to people who asked for your messages, and say who you are and how to stop them in your first message.

Webhooks

Subscribe to them like any other webhook event. Sandbox environments receive simulated replies only (testing).