Send a text MCP OpenAI SDK

curl -X POST https://api.omniocto.com/v1/messages \
  -H "Authorization: Bearer $OMNI_OCTO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "channel": "sms",
        "from": "+16285550100",
        "to": "+14155550123",
        "text": "Hello from Omni Octo" }'

# Claude Code: your browser opens, pick a workspace, Allow
claude mcp add --transport http omniocto \
  https://api.omniocto.com/mcp

# Codex
codex mcp add omniocto --url https://api.omniocto.com/mcp
codex mcp login omniocto

from openai import OpenAI

client = OpenAI(
    api_key="sk-octo_…",
    base_url="https://api.omniocto.com/v1",
)
resp = client.responses.create(
    model="claude-sonnet-4-6",
    input="Which numbers can I text from?",
)

Texts, WhatsApp and AI phone calls, for your code and your AI agent

Q: What is Omni Octo?

Omni Octo is an AI platform for business messaging and calls: SMS, WhatsApp, email and AI phone calls, campaigns, contacts, a shared inbox, AI agents and workflows. These docs cover the three ways in: the MCP server at https://api.omniocto.com/mcp, the REST API at https://api.omniocto.com/v1, and the OpenAI-compatible API.

Q: Can I try the API without spending?

Campaign drafts, previews, webhook test events and every GET request are free. A call to your own phone from the shared trial number needs no card, within its daily cap. A text or call to yourself otherwise costs a little, as listed on the Test without spending page.

Q: How can an AI agent read these docs?

Fetch https://docs.omniocto.com/llms.txt for an index or /llms-full.txt for the whole site, append .md to any page URL for its Markdown, read the OpenAPI document at /openapi/v1.json, or search the docs live through the MCP server at https://api.omniocto.com/mcp-docs.

Omni Octo is an AI platform for business messaging and calls — SMS, WhatsApp, email and AI phone calls, campaigns, contacts, a shared inbox, AI agents and workflows. These docs show the three ways in: the /mcp server for Claude, ChatGPT/Codex and Cursor, the /v1 REST API, and an OpenAI-compatible API.

Quickstart Connect your AI agent API reference

Three ways to use Omni Octo

Everything works on one workspace: the numbers, agents, contacts and credits you set up in the dashboard. Pick the door that fits how you build.

MCP server for AI agents

One server, https://api.omniocto.com/mcp, for Claude, ChatGPT/Codex, Claude Code, Cursor and any MCP client. Your agent texts, calls, runs campaigns and reads the inbox, and asks you before anything risky. Sign in with your account, or use an API key for scripts. MCP server overview

Platform API (/v1)

A REST API at https://api.omniocto.com/v1 with one shape for every channel: SMS, MMS and WhatsApp messages, AI phone calls, campaigns, contacts, the inbox, webhooks and billing. Platform API overview

OpenAI-compatible API

Talk to Octo, the workspace’s AI assistant, from the OpenAI SDK, LangChain, LiteLLM or n8n: change base_url and api_key, then call /v1/responses or /v1/chat/completions. OpenAI-compatible API overview

Docs your agent can read

llms.txt, the whole site in one file, every page as Markdown, the OpenAPI document, and a docs-search MCP server that needs no account. Resources for AI agents

Quickstart: your first text or call in five minutes

The short path. Each step links to the page with every detail.

Create an API key in the dashboard under Settings → API Keys & Webhooks (Get an API key), and put it in a variable:
Terminal window
```
export OMNI_OCTO_API_KEY=sk-octo_…
```
Check the key and read your own phone number (user_phone), the one you will text and call:
Terminal window
```
curl https://api.omniocto.com/v1/me -H "Authorization: Bearer $OMNI_OCTO_API_KEY"
```
Find a number to send from. Each sender says, per channel, whether it is ready (sms.ready, whatsapp.ready, voice.ready) and, if not, how to fix it:
Terminal window
```
curl https://api.omniocto.com/v1/senders -H "Authorization: Bearer $OMNI_OCTO_API_KEY"
```

Text yourself from a number whose sms.ready is true:

curl -X POST https://api.omniocto.com/v1/messages \
  -H "Authorization: Bearer $OMNI_OCTO_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "channel": "sms", "from": "+16285550100", "to": "+14155550123", "text": "Hello from Omni Octo" }'

A number can text only after carrier registration (usually 1 to 3 weeks). No cleared number yet? Have an AI agent call you from the shared trial number (the sender with "trial": true), no card needed, once you choose its agent in the dashboard:

curl -X POST https://api.omniocto.com/v1/calls \
  -H "Authorization: Bearer $OMNI_OCTO_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "from": "pfn-0000000001", "to": "+14155550123", "mission": "Say hello and ask what I would like to automate first." }'

Next: follow the text’s status, add a webhook and run a one-person campaign in the full quickstart, or place a call step by step.

Add the server, then start Claude Code. Your browser opens (or type /mcp and choose Authenticate): choose a workspace and click Allow. No key needed.

claude mcp add --transport http omniocto https://api.omniocto.com/mcp

Then ask: “Which numbers can I text from? Text my own phone a hello, but ask me first.” For scripts and CI, pass a key instead: Connect any MCP client.

codex mcp add omniocto --url https://api.omniocto.com/mcp
codex mcp login omniocto

codex mcp login opens your browser to sign in. In the ChatGPT desktop app, add the server under Settings instead: Connect ChatGPT and Codex.

In the Claude desktop app or on claude.ai, add a custom connector (name it Omni Octo) with the address https://api.omniocto.com/mcp, and sign in. The step-by-step guide, with screenshots and the tool permissions we recommend: Connect Claude.

Clients that read an mcpServers file (Cursor’s is ~/.cursor/mcp.json) take the URL; the client opens a browser to sign in:

{
  "mcpServers": {
    "omniocto": {
      "url": "https://api.omniocto.com/mcp"
    }
  }
}

With a key instead, and the other ways to connect: Connect any MCP client.

Start each area with a prompt

Each area below has a guide, a field reference and a prompt to paste into your own coding agent (Claude Code, Codex, Cursor). The prompts send texts and calls only to your own number, and tell the agent to ask you before it sends, spends or changes anything.

Connect your AI agent with MCP

Add the Omni Octo MCP server once, and your agent finds the right tool for each job by searching. MCP server overview · API tools · Octo’s tools

Add the Omni Octo MCP server to this client: name it omniocto, URL https://api.omniocto.com/mcp, transport Streamable HTTP (in Claude Code: claude mcp add --transport http omniocto https://api.omniocto.com/mcp). I will sign in when the browser opens. Once connected, use find_tools and run_tool to tell me which of my numbers can send texts, which can place calls, and my credit balance. Do not send, call or change anything.

Send SMS and WhatsApp messages

Send a text, a picture (MMS) or an approved WhatsApp template with one request, and follow it to delivered. Send a text · Send a WhatsApp template · Messages reference

Read https://docs.omniocto.com/platform-api/sms.md. Write a small script that reads my Omni Octo API key from OMNI_OCTO_API_KEY, gets my own phone number (user_phone) from GET /v1/me, picks a sender from GET /v1/senders whose sms.ready is true, and sends one SMS to my own number only, with an Idempotency-Key. Show me the request and ask me before you run it. Then poll GET /v1/messages/{id} until the status is final and explain any error code from the guide.

Place AI phone calls

An AI agent calls one number with a mission you write in plain words, then you read how it went: the summary, the answers it collected and the transcript. Place a call · Read call transcripts · Calls reference

Read https://docs.omniocto.com/platform-api/voice.md. Using my Omni Octo API key from OMNI_OCTO_API_KEY, place one AI phone call to my own phone (user_phone from GET /v1/me) from the shared trial number (the sender with "trial": true in GET /v1/senders), with a one-sentence mission. Ask me before placing it. Afterwards read the call with GET /v1/calls/{id} and its transcript with GET /v1/calls/{id}/transcript, and summarise how it went.

Run campaigns: bulk SMS, WhatsApp and AI calls

Send to a whole list or segment: create a draft, preview who it reaches and what it costs, start exactly that, and choose what each call should find out. Run a campaign · Choose what calls find out · From Claude Code or Codex

Using the omniocto MCP server (guide: https://docs.omniocto.com/mcp/claude-code-campaigns.md), draft an AI call campaign whose only recipient is my own phone number. Use find_tools to find the campaign tools. Create it as a draft, preview it, and tell me who it reaches, who is skipped and what it would cost. Do not start it until I say so. After it runs, read each call's results and suggest one change to the agent for the next round.

Keep contacts, lists and segments

Create and find the people you text and call, give them several numbers and emails, tag them, record opt-outs, and group them into lists and segments. Keep contacts · Build a segment · Contacts reference

Read https://docs.omniocto.com/platform-api/contacts.md. Write a script that imports contacts from a CSV I give you into Omni Octo with POST /v1/contacts (an Idempotency-Key per row, handling a contact that already exists the way the guide says), tags them, and adds them to a new list. Run it on a two-row sample first and show me the results before importing the rest. Never mark anyone as opted out unless the CSV says so.

Work the inbox

Read conversations on every channel, page through what was said, reply in the thread, hand a conversation to a person or close it. Work the inbox · Conversations reference

Using the omniocto MCP server, show me my ten most recent conversations across channels, each with the contact, the channel and the last message. Draft a reply for any that look unanswered, but send nothing until I approve each reply.

Receive webhooks and events

Have every delivery, reply, call and campaign change POSTed to your server, signed, with retries, or read the same events as a stream. Receive webhooks · Events reference

Read https://docs.omniocto.com/platform-api/events.md. Write a small webhook receiver (Node or Python) that verifies the Omni Octo signature and logs message.status_updated, message.received and call events. When I give you a public https URL, register it with POST /v1/webhooks and send a test event with POST /v1/webhooks/{id}/test. Ask me before registering, and store the secret only in an environment variable.

Talk to Octo with the OpenAI SDK

Octo is the workspace’s AI assistant, with the same tools and approvals as in the dashboard. Any tool that speaks the OpenAI API can use it. OpenAI-compatible API overview · Confirmations

Read https://docs.omniocto.com/openai-api/overview.md. Point the OpenAI Python SDK at https://api.omniocto.com/v1 with my Omni Octo key from OMNI_OCTO_API_KEY, and ask Octo "Which numbers can I send from?" with the Responses API. Continue the conversation with previous_response_id. If Octo asks to confirm anything that sends, spends or changes data, stop and show me instead of confirming.

What tools are available

MCP tools at `https://api.omniocto.com/mcp`

Two tools do the most common jobs by name; the other four reach everything else a workspace can do.

Tool	What it does
`send_sms`	Send an SMS from one of the workspace’s numbers, after the user’s OK.
`place_call`	Place an AI phone call from one of the workspace’s numbers, after the user’s OK.
`find_tools`	Search the tools by what you want to do (“text a contact”, “pause a campaign”, “docs on webhooks”).
`describe_tool`	One tool’s description, risk, how it is approved, and input schema.
`run_tool`	Run any tool found with `find_tools`.
`confirm_action`	Approve or cancel a risky call, for apps without approval forms.

Through run_tool your agent reaches three sets of tools, each filtered by your role in the workspace:

API tools: the Platform API as tools. Texts and WhatsApp templates, AI calls, campaigns, contacts and lists, the inbox, events.
Octo’s tools: what the dashboard’s assistant can do. AI agents and their knowledge, phone numbers, workflows, segments, billing, and bulk changes in one approved call.
Docs search: search_docs and get_doc read this site.

Platform API (`/v1`) at a glance

Area	Main endpoints	Guide
Messages: SMS, MMS, WhatsApp	`POST /v1/messages`, `GET /v1/messages`, `POST /v1/media`	Send a text, WhatsApp
AI phone calls	`POST /v1/calls`, `GET /v1/calls/{id}/transcript`, `GET /v1/recordings/{conversation_id}`	Place a call
Campaigns	`POST /v1/campaigns`, `POST /v1/campaigns/{id}/previews`, `POST /v1/campaigns/{id}/start`	Run a campaign
What calls find out	`POST /v1/insights`	Insights
Contacts, lists, segments	`POST /v1/contacts`, `GET /v1/lists`, `GET /v1/segments`	Keep contacts
Inbox	`GET /v1/conversations`, `POST /v1/conversations/{id}/messages`	Work the inbox
Webhooks and events	`POST /v1/webhooks`, `GET /v1/events`	Receive webhooks
Senders, templates, agents	`GET /v1/senders`, `GET /v1/templates`, `GET /v1/agents`	Reference
Account and billing	`GET /v1/me`, `GET /v1/balance`, `GET /v1/usage`	Billing and credits
Talk to Octo (OpenAI-compatible)	`POST /v1/responses`, `POST /v1/chat/completions`, `GET /v1/models`	Overview

Every field of every endpoint: Platform API reference. Every operation with a try-it console: interactive reference.

Questions

What is Omni Octo? An AI platform for business messaging and calls: SMS, WhatsApp, email and AI phone calls, campaigns, contacts, a shared inbox, AI agents and workflows. These docs cover the three ways in: the MCP server, the REST API (/v1) and the OpenAI-compatible API.

Do I need an API key to use the MCP server? No. In Claude, Claude Code, Codex and other clients that support MCP sign-in, you sign in with your Omni Octo account and choose a workspace. Use a key for scripts, CI and clients that cannot sign in (Authentication).

Can I try the API without spending? Campaign drafts, previews, webhook test events and every GET are free. A call to your own phone from the shared trial number needs no card, within its daily cap. A text or call to yourself otherwise costs a little: Test without spending.

Which AI clients can use Omni Octo? Any MCP client that speaks Streamable HTTP: the Claude desktop app and claude.ai, Claude Code, Codex in the ChatGPT desktop app, the Codex CLI, Cursor and others. Tools that speak the OpenAI API can use the OpenAI-compatible API.

How can an AI agent read these docs? Fetch /llms.txt for an index or /llms-full.txt for the whole site, append .md to any page’s URL for its Markdown, read /openapi/v1.json, or search live through https://api.omniocto.com/mcp-docs: Agent resources.

Keep going

Quickstart From an API key to a text, its status, a webhook and a one-person campaign.

Test without spending What is free, what costs a little, and how to test on your own phone.

Errors Every error code of the Platform API and how to fix it.

Changelog What changed in the API, the MCP server and these docs.