API reference
API reference
Every endpoint, object and webhook event of the OmniMessage API. This reference is generated from the OpenAPI 3.1 document, so it always matches the published contract.
Basics#
The OmniMessage API is JSON over HTTPS. Requests and responses use UTF-8, snake_case field names and ISO-8601 UTC timestamps. Money is an integer number of micro-USD in fields ending _micros (1 USD = 1,000,000), accompanied by currency: "USD".
Authenticate with an API key as a bearer token. Keys prefixed om_live_ deliver and bill; keys prefixed om_test_ run against a sandbox where nothing is delivered or billed.
| Topic | Summary | Guide |
|---|---|---|
| Authentication | Authorization: Bearer <api key>. Each operation lists the scope it requires. | Authentication |
| Errors | Non-2xx responses carry an error object with a type and a stable code. | Errors |
| Idempotency | Idempotency-Key on POST requests makes retries safe for 24 hours. | Idempotency |
| Pagination | limit (1 to 100, default 20) and starting_after on list endpoints. | Pagination |
| Rate limits | 100 requests per second on POST /v1/messages, 20 elsewhere, per API key. | Rate limits |
| Request IDs | Every response has an X-Request-Id header, repeated as request_id in errors. | Errors |
https://api.omnimessage.co/v1Authorization: Bearer om_live_xxxxxxxxxxxxxxxxxxxxxxxxcurl https://api.omnimessage.co/v1/me \
-H "Authorization: Bearer om_live_xxxxxxxxxxxxxxxxxxxxxxxx"{
"object": "account",
"id": "acc_8nM3bV6cX9zL2kJ5hG1f",
"name": "Acme Logistics",
"mode": "live",
"api_key": {
"id": "key_1qW4eR7tY0uI3oP6aS9d",
"name": "Production backend",
"scopes": [
"messages:write",
"messages:read",
"channels:read"
]
},
"capabilities": [
"automation_events",
"webhook_filters",
"test_inbound",
"events_feed"
]
}Endpoints#
Messages
Send messages on any connected channel, alone or in batches, and read back their status and history.
Channels
Connect and manage your own senders: WhatsApp Business numbers, Telegram bots, SMS numbers and more.
Webhook endpoints
Register the URLs that receive delivery receipts, inbound messages and account events.
- POST
/v1/webhook_endpointsCreate a webhook endpoint - GET
/v1/webhook_endpointsList webhook endpoints - GET
/v1/webhook_endpoints/{id}Retrieve a webhook endpoint - PATCH
/v1/webhook_endpoints/{id}Update a webhook endpoint - DELETE
/v1/webhook_endpoints/{id}Delete a webhook endpoint - POST
/v1/webhook_endpoints/{id}/roll_secretRoll the signing secret - POST
/v1/webhook_endpoints/{id}/testSend a test event
Contacts
Keep the people you message, with their consent, tags and custom attributes, and group them in lists and segments.
- POST
/v1/contactsCreate a contact - GET
/v1/contactsList contacts - POST
/v1/contacts/upsertCreate or update a contact by phone number - POST
/v1/contacts/tagsAdd and remove tags in bulk - GET
/v1/contacts/{id}Retrieve a contact - PATCH
/v1/contacts/{id}Update a contact - DELETE
/v1/contacts/{id}Delete a contact - GET
/v1/contact_tagsList tags - POST
/v1/contact_listsCreate a contact list - GET
/v1/contact_listsList contact lists - GET
/v1/contact_lists/{id}Retrieve a contact list - PATCH
/v1/contact_lists/{id}Update a contact list - DELETE
/v1/contact_lists/{id}Delete a contact list - POST
/v1/contact_lists/{id}/membersAdd contacts to a list - POST
/v1/contact_lists/{id}/members/removeRemove contacts from a list - GET
/v1/segmentsList segments - GET
/v1/segments/{id}Retrieve a segment - GET
/v1/segments/{id}/previewCount the contacts of a segment
Campaigns
Send one message to many recipients, on a schedule and at a controlled rate, and follow the progress.
- POST
/v1/campaignsCreate a campaign - GET
/v1/campaignsList campaigns - GET
/v1/campaigns/{id}Retrieve a campaign - GET
/v1/campaigns/{id}/recipientsList the recipients of a campaign - POST
/v1/campaigns/{id}/launchLaunch a campaign - POST
/v1/campaigns/{id}/pausePause a campaign - POST
/v1/campaigns/{id}/resumeResume a campaign - POST
/v1/campaigns/{id}/cancelCancel a campaign
Integration sources
Register the stores and sites that report events, and let a plugin read which events to send.
- POST
/v1/integration_sourcesRegister an integration source - GET
/v1/integration_sourcesList integration sources - GET
/v1/integration_sources/currentRetrieve the source of a source key - PATCH
/v1/integration_sources/currentDescribe the source of a source key - GET
/v1/integration_sources/{id}Retrieve an integration source - PATCH
/v1/integration_sources/{id}Update an integration source - DELETE
/v1/integration_sources/{id}Delete an integration source - POST
/v1/integration_sources/{id}/roll_keyRoll the key of an integration source
Automation events
Report what happened in a store or site; the account decides in the console what message follows.
Event feed
Read the events webhooks deliver, for polling and for catching up after an outage.
Billing
Read the prepaid balance, the per-message prices and usage.
Account
Inspect the account and API key behind a request.
Objects#
The resources returned by the API, with every attribute and an example.
Webhook events#
The payload of each event type. For setup, signatures and retries, read the webhooks guide.
OpenAPI document#
Import the document into an API client or feed it to a code generator. It is available at /docs/openapi.json and lists the required scope of each operation under x-scopes.