Quickstart - Comms

Use this page the first time you connect Comms to your app or backend. You will open the dashboard, create a Messages API key, send a message, and optionally receive a webhook.

Keep COMMS_API_KEY on your server. Do not put Messages API keys in browser code, mobile apps, or public repositories.

Set up your workspace

Go to comms.osis.co/dashboard and sign in with your phone. That creates (or opens) the workspace that owns your line, keys, and inbox.

Open Messages API keys

In the product, open Messages API — or use the Create Messages key control in the top bar.

Create a Messages API key

For the quickest path, create a key with the default scopes: Send messages and Read messages. That is enough to send and list traffic on your line. Building a long-running integration? Prefer a named key per environment (Local development, Production worker) so you can rotate without guessing.

Create a key

Click Create key. Name it something you will recognize later, like Production backend or Staging worker.

Choose what the key can do

Defaults cover most backends:

Scope	Purpose
`comms_send`	Outbound SMS / iMessage
`comms_read`	List messages, conversations, contacts, delivery events
`comms_webhooks`	Optional — register webhook URLs

Leave webhooks off until you need push. You can mint a second key later with only the scopes that job needs.

Copy the secret once

Store it in your environment as COMMS_API_KEY. The full value is only shown once — rotate if you lose it.

COMMS_API_KEY=osis_xxxxxxxxxxxxxxxxx

Send your first message

Confirm the key works by sending a short text to a number you control.

curl -X POST "https://osis.co/api/v1/comms/messages" \
  -H "Authorization: Bearer $COMMS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: demo-$(date +%s)" \
  -d '{
    "to": "+12125550147",
    "body": "Hello from Comms"
  }'

const res = await fetch("https://osis.co/api/v1/comms/messages", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.COMMS_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": `demo-${Date.now()}`,
  },
  body: JSON.stringify({
    to: "+12125550147",
    body: "Hello from Comms",
  }),
});

console.log(res.status, await res.json());

import os, time, requests

r = requests.post(
    "https://osis.co/api/v1/comms/messages",
    headers={
        "Authorization": f"Bearer {os.environ['COMMS_API_KEY']}",
        "Content-Type": "application/json",
        "Idempotency-Key": f"demo-{int(time.time())}",
    },
    json={"to": "+12125550147", "body": "Hello from Comms"},
)
print(r.status_code, r.json())

A successful create returns 202 with a message object. Retries with the same Idempotency-Key return 200 and "duplicate": true without sending again.

Always send an Idempotency-Key on outbound traffic. Retries, double-clicks, and queue redeliveries should never double-text a customer. See Idempotency.

Read traffic back

curl "https://osis.co/api/v1/comms/messages?limit=20" \
  -H "Authorization: Bearer $COMMS_API_KEY"

Requires comms_read. Filter with conversation_id, since, or direction.

Optional: see a webhook

If you want push instead of poll:

Expose a local HTTPS endpoint

Add a POST route in your app and tunnel it with ngrok, Cloudflare Tunnel, or similar while developing.

Mint (or update) a key with webhooks

Ensure the key includes the comms_webhooks scope.

curl -X POST "https://osis.co/api/v1/comms/webhooks" \
  -H "Authorization: Bearer $COMMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-tunnel.example.com/hooks/comms",
    "events": ["message.received", "message.sent"]
  }'

Full guide: Webhooks.

Next steps

Send guide

Body fields, channels, and delivery behavior in depth.

API overview

Base URL, errors, and the full endpoint map.

Authentication

Scopes, rotation, and what the key is (and is not).

Errors & rate limits

Status codes, 429 handling, and retry advice.

​Set up your workspace

​Create a Messages API key

​Send your first message

​Read traffic back

​Optional: see a webhook

​Next steps

Send guide

API overview

Authentication

Errors & rate limits

Set up your workspace

Create a Messages API key

Send your first message

Read traffic back

Optional: see a webhook

Next steps