Ogave SMS Messaging API

Send SMS to 19+ countries, WhatsApp messages and voice calls with one API, with automatic fallback between channels; follow every message to the handset, and receive replies. REST + JSON, base URL https://app.ogave.co/v1. Machine-readable spec: OpenAPI 3.1 (YAML) · Postman collection + environment · SDKs & tools.

Quick start

1. Create an account in the portal, top up, and request a sender ID (e.g. your brand).
2. Developers → API keys → create a test_ key and a live_ key. Keys are shown once.
3. Send your first message with the test key (nothing is sent or charged), then switch to the live key.

curl https://app.ogave.co/v1/messages \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-42-shipped" \
  -d '{"to": "+573001234567", "from": "SHOP", "text": "Your order 42 has shipped", "client_ref": "order-42"}'

// Node 18+ (built-in fetch)
const res = await fetch("https://app.ogave.co/v1/messages", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "order-42-shipped",
  },
  body: JSON.stringify({ to: "+573001234567", from: "SHOP", text: "Your order 42 has shipped", client_ref: "order-42" }),
});
const message = await res.json();
if (!res.ok) throw new Error(`${message.error.code}: ${message.error.message} (${message.error.request_id})`);
console.log(message.id, message.status, message.price, message.currency);

import os, requests

res = requests.post(
    "https://app.ogave.co/v1/messages",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}", "Idempotency-Key": "order-42-shipped"},
    json={"to": "+573001234567", "from": "SHOP", "text": "Your order 42 has shipped", "client_ref": "order-42"},
    timeout=10,
)
body = res.json()
if not res.ok:
    raise RuntimeError(f"{body['error']['code']}: {body['error']['message']} ({body['error']['request_id']})")
print(body["id"], body["status"], body["price"], body["currency"])

<?php
$ch = curl_init('https://app.ogave.co/v1/messages');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('API_KEY'),
        'Content-Type: application/json',
        'Idempotency-Key: order-42-shipped',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'to' => '+573001234567', 'from' => 'SHOP', 'text' => 'Your order 42 has shipped', 'client_ref' => 'order-42',
    ]),
]);
$body = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($status >= 400) {
    throw new RuntimeException("{$body['error']['code']}: {$body['error']['message']}");
}
echo $body['id'], ' ', $body['status'], PHP_EOL;

Response 201 Created with the message object: status is queued, and you get encoding, segments and price right away.

Authentication

Send the key in the header: Authorization: Bearer live_…. Never put keys in URLs: a request with a key in the query string is refused (key_in_url). Keys are stored hashed; we show them once. Create as many as you need (one per system), see when each was last used and revoke any of them from the portal.

Every response has an X-Request-Id header. Send your own X-Request-Id (8-64 chars) to correlate logs.

Test mode

test_ keys run the same validation, pricing and responses as live keys, keep their data separate, and never reach an operator or touch your balance. Test messages move queued → sent → delivered within ~3 seconds and fire your webhooks (with "mode": "test"). Magic numbers force other outcomes:

POST /v1/messages

Sending rules: frequency cap and quiet hours

Set in the portal (Messaging › Sending rules; the platform default applies until you save your own) and applied to every marketing message: API (category: "marketing"), Send SMS, campaigns and multichannel campaigns. Transactional messages are never delayed or capped.

• Quiet hours (e.g. 21:00–08:00) are those of the recipient: the time zone comes from the number (its country, or its area code where a country has several zones; otherwise the country's main zone). A message that would arrive in the quiet hours is accepted with status: "scheduled", scheduled_at = end of the quiet hours and delayed_by: "quiet_hours". Like any scheduled message it is charged when it is released and can be canceled until then. A scheduled_at you send is checked at that time.
• Frequency cap: at most N marketing messages per number per day and/or per week (Monday–Sunday), counted in the recipient's time zone on the day the message goes out. Over the cap the message is refused with frequency_capped (422; in a batch only that item) and nothing is charged. Messages refused for another reason (e.g. balance) do not use up the cap.
• Test keys show the same outcome (scheduled / frequency_capped) without counting towards the cap.

SMS templates and approval

New and edited SMS templates are reviewed by our team (pending → approved or rejected with a reason, shown in the portal; editing the text sends it back to review). If your plan has the rule only approved templates can be sent, every SMS text (/v1/messages, batch items, SMS fallback steps) must come from an approved template: send its template_id, or a text equal to an approved template where each {placeholder} is replaced by some text. Otherwise the message is refused with template_required. A pending, rejected or disabled template_id gives template_not_approved; an unknown one unknown_template. Placeholders are not filled by the API: replace them yourself in text.

Short links

Codes are 7 random characters (letters and digits), valid 90 days. The link answers 302 to your destination with its query string (and any query added by the visitor). Link previews (WhatsApp, iMessage, Telegram, Slack, Facebook, Google, Apple and other bots, HEAD and prefetch requests) are recorded as previews, never as clicks. Refused destinations (link_refused): other than http/https, localhost or private / reserved IP addresses, links with user:password@, other URL shorteners (bit.ly, tinyurl.com…) and blocked domains. Disabled or expired links answer 410. Verify codes are never shortened.

POST /v1/messages/batch

Up to 1,000 recipients per call. Top-level from, text, scheduled_at, validity, callback_url, flash, shorten_urls, track_clicks, template_id, category apply to every item; items can override them. Each recipient is validated and charged on its own; the response lists a result per index (message or error), with accepted, rejected and total_price.

curl https://app.ogave.co/v1/messages/batch \
  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{
    "from": "SHOP",
    "text": "Flash sale today: 20% off",
    "messages": [
      {"to": "+573001234567"},
      {"to": "+56987654321", "text": "Oferta: 20% hoy", "client_ref": "cl-1"}
    ]
  }'

Message object

{
  "id": "msg_01m65jn6f5x9jej71dmq941vkb",
  "object": "message",
  "mode": "live",
  "to": "+56987654321",
  "from": "SHOP",
  "text": "Live API test: código 1234",
  "client_ref": "live-1",
  "status": "delivered",
  "error": null,
  "encoding": "UCS-2",
  "segments": 1,
  "price": "0.0280",
  "currency": "USD",
  "country": "CL",
  "scheduled_at": null,
  "expires_at": "2026-11-01T04:56:27Z",
  "category": "transactional",
  "delayed_by": null,
  "callback_url": null,
  "created_at": "2026-10-30T04:56:27Z",
  "submitted_at": "2026-10-30T04:56:27Z",
  "done_at": "2026-10-30T04:56:54Z"
}

Statuses

WhatsApp and voice messages add read, ringing, answered, completed, busy and no_answer: see Channel statuses.

GET /v1/messages/{id} · GET /v1/messages

List newest first, limit 1–100 (default 20), cursor pagination with starting_after=<next_cursor>. Filters: status, to, from, client_ref, created_after, created_before.

curl "https://app.ogave.co/v1/messages?status=delivered&limit=50" -H "Authorization: Bearer $API_KEY"
# next page: add &starting_after=<next_cursor>

DELETE /v1/messages/{id}

Cancels a scheduled message. Other statuses return not_cancelable.

POST /v1/emails

Send one email from your app and follow it through delivery. Use an address of one of your verified domains (GET /v1/email-identities); without from it goes from your default sender, or from the platform address with replies to your account email. Priced per email; test keys (test_…) simulate the whole timeline and are free. Scope email:send (email:read to read). Idempotency-Key works as on every POST.

curl https://app.ogave.co/v1/emails \
  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" -H "Idempotency-Key: receipt-1001" \
  -d '{"to": "ana@example.com", "from": "hola@yourshop.com", "subject": "Your receipt #1001",
       "html": "<p>Thanks for your order</p>", "tags": ["receipt"], "metadata": {"order_id": "1001"},
       "attachments": [{"filename": "receipt-1001.pdf", "content": "JVBERi0xLjQK…"}]}'

Email object and timeline

GET /v1/emails/{id} and GET /v1/emails (newest first; filters status, to, from, tag, client_ref, created_after, created_before, limit, starting_after) return the email with events: every step with its time, in the order they happened.

status is where the email is: accepted, sent, deferred, delivered, bounced, failed, complained or canceled; opened, clicked and unsubscribed are flags with opens, clicks, opened_at, clicked_at. The same email is also in /v1/messages (channel: email) and in the portal under Channels › Email › Log, with its timeline.

Email webhooks

Each event of an email sent with /v1/emails is posted to its callback_url or your status URL, signed like every webhook (Webhook-Signature): email.sent, email.delivered, email.deferred, email.bounced, email.failed, email.complained, email.opened, email.clicked, email.unsubscribed. data is the email object plus event {type, at, detail?, url?}. Emails sent with /v1/messages keep their message.* webhooks.

GET /v1/email-identities

What from may be: your sending domains (status pending / verified and the DNS checks), the sender addresses on them (default, usable = its domain is verified) and the platform address. Add domains and senders in Channels › Email.

Delivery events from the mail provider

The platform reads delivery events from its mail provider (Amazon SES through SNS, Mailgun webhooks, or an SMTP relay). A relay posts them to the webhook URL shown in the admin panel, signed with its webhook secret:

POST /webhooks/email/mailer/<account>
X-Signature: sha256=<hex HMAC-SHA256 of the raw body with the webhook secret>
{"events": [{"message_id": "<Message-ID of the email>", "event": "delivered", "timestamp": 1793750400, "detail": "250 2.0.0 OK"}]}
# event: delivered | deferred | bounced | complained | opened | clicked | unsubscribed

Balance and pricing

GET /v1/balance → {"balance": "48.8390", "currency": "USD", "unlimited": false}
GET /v1/pricing?to=%2B573001234567 → country and price per segment for that number.
GET /v1/pricing/countries → your whole price list.

Webhooks

Set your URLs with PUT /v1/webhooks (status_url, inbound_url) or in the portal. Events: message.sent, message.delivered, message.undelivered, message.expired, message.rejected, message.failed, message.inbound (replies to your numbers), message.clicked (a person opened a short link of the message: the message object plus url, short_url, clicked_at, device, os, browser; one event per click, link previews excluded), and the Verify events. WhatsApp and voice add more status events and WhatsApp inbound messages. Messages sent from the portal (campaigns, quick send, files) also produce message.* status webhooks, with "source": "portal" and the campaign_id. The body is {"id","type","mode","created_at","data"} with the message object in data.

POST /your/status/url HTTP/1.1
Content-Type: application/json
Webhook-Event: message.delivered
Webhook-Delivery: whd_01m65jnr2e3x4d5f6g7h8j9k0m
Webhook-Signature: t=1793336214,v1=5f2b0c0e9d6a…

{"id":"evt_01m65jnr…","type":"message.delivered","mode":"live","created_at":"2026-10-30T04:56:54Z","data":{ …message object… }}

Verify signatures

Webhook-Signature: t=<unix time>,v1=<hex HMAC-SHA256(secret, t + "." + raw body)>. Compute it over the raw body, compare in constant time, and reject timestamps older than 5 minutes. (Receivers built before November 2026 may read the same values under the older header names, which are still sent.) Get or rotate the secret in the portal or with POST /v1/webhooks/rotate-secret (shown once).

import crypto from "node:crypto";

// Use the RAW request body (e.g. express.raw({ type: "application/json" })).
export function verifyWebhookSignature(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=", 2)));
  if (!parts.t || !parts.v1) return false;
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > toleranceSeconds) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

import hashlib, hmac, time

def verify_signature(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    try:
        parts = dict(p.split("=", 1) for p in header.split(","))
        if abs(time.time() - int(parts["t"])) > tolerance:
            return False
        expected = hmac.new(secret.encode(), parts["t"].encode() + b"." + raw_body, hashlib.sha256).hexdigest()
        return hmac.compare_digest(expected, parts["v1"])
    except (KeyError, ValueError):
        return False

<?php
function verifyWebhookSignature(string $rawBody, string $header, string $secret, int $tolerance = 300): bool
{
    if (!preg_match('/^t=(\d+),v1=([0-9a-f]{64})$/', $header, $m)) {
        return false;
    }
    if (abs(time() - (int) $m[1]) > $tolerance) {
        return false;
    }
    return hash_equals(hash_hmac('sha256', $m[1] . '.' . $rawBody, $secret), $m[2]);
}
// $ok = verifyWebhookSignature(file_get_contents('php://input'), $_SERVER['HTTP_WEBHOOK_SIGNATURE'] ?? '', $secret);

Retries and delivery log

Any 2xx response within 5 seconds counts as delivered. Otherwise we retry after 1 min, 5 min, 30 min, 2 h and 12 h, then mark the delivery failed. Redirects are not followed. Every attempt is logged (status code, first 1 KB of your answer): GET /v1/webhooks/deliveries, and resend any of them with POST /v1/webhooks/deliveries/{id}/retry (or from the portal). Use data.id + type to de-duplicate: a webhook may arrive more than once.

Idempotency

Send Idempotency-Key: <your unique id> (≤ 64 chars) on any POST request (messages, batch, conversions, Verify, contacts, reports, hooks…). Retrying with the same key and the same body within 24 hours returns the original response with Idempotent-Replayed: true and never acts twice, including when the first answer was an error. The body is compared as JSON (key order and spacing do not matter). The same key with a different body is refused with 409 idempotency_conflict; a request still running with the key gets 409 idempotency_in_progress (retry after a second). Keys are scoped to your account and key mode. The official SDKs add a key to every POST automatically, so their retries are safe; client_ref stays your own reference and is not used for de-duplication.

Rate limits

Each key allows 50 requests per second by default (ask us for more). Above that you get 429 rate_limited with Retry-After; every response has X-RateLimit-Limit and X-RateLimit-Remaining. A batch call counts as one request.

Errors

All errors have the same shape and a request_id. param names the offending field when there is one.

HTTP/1.1 402 Payment Required
X-Request-Id: req_01m65jmsn5wwdhwfejxhx2mvy0

{
  "error": {
    "code": "insufficient_balance",
    "message": "Your balance does not cover this message. Top up in the portal.",
    "doc_url": "https://app.ogave.co/docs/api#errors-insufficient_balance",
    "request_id": "req_01m65jmsn5wwdhwfejxhx2mvy0"
  }
}

Billing

Price per segment for the destination country, from your plan (GET /v1/pricing/countries). Charged when the message is queued (immediately, or at scheduled_at). Refunded if the network rejects it at submission, if it expires before submission, or if you cancel a scheduled message. Delivery receipts don't change the charge. Test keys are never charged.

Reports

Exports run in the background so they never time out: POST /v1/reports with type (messages = one row per message, summary, transactions), date_from, date_to (up to 12 months per export), timezone, optional filters (status, country, network MCC-MNC, sender, campaign_id, source, api_key_id, account_id, destination, text, error_code), columns, format (csv or xlsx), delimiter, gzip. It answers 202 with id (rep_…). Poll GET /v1/reports/{id} until status is ready and download download_url (signed, no API key needed, valid 7 days). POST /v1/reports/{id}/cancel stops it. CSV files are UTF-8 with BOM; cells starting with = + - @ are prefixed with '. Verify codes are always masked. Use GET /v1/messages for live lookups of single messages.

Data retention. Message details are kept for 3 months; up to 12 months on request. messages exports and GET /v1/messages cover the last 3 months; older periods are archived and can be requested in the portal (Reports › Archived messages, usually a few minutes). summary exports, dashboards and statements work for any period: daily summaries are kept forever.

curl -X POST https://app.ogave.co/v1/reports -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{"type":"messages","date_from":"2026-10-01","date_to":"2026-10-31","timezone":"America/Bogota","filters":{"country":["CO"],"status":["undelivered"]}}'

Conversion tracking

A conversion means the recipient did what the message asked (bought, signed in, booked). Send with "conversion_tracking": true and tell us when it happens, up to 7 days after sending. Conversion rates per country, network, sender ID, campaign, template and day are in Reports › Conversions (and CSV). An approved Verify code counts automatically.

curl -X POST https://app.ogave.co/v1/messages -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{"to":"+573001234567","from":"SHOP","text":"Your cart is waiting: 10% off today","conversion_tracking":true}'

curl -X POST https://app.ogave.co/v1/messages/msg_01jb…/conversion -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{"event":"purchase","value":49.90,"currency":"USD"}'

Answers 201 with the conversion object; repeating the call for the same message answers 200 with the same conversion (the first one stays).

{"id":"conv_01jb…","object":"conversion","mode":"live","source":"api","message_id":"msg_01jb…","campaign_id":null,
 "event":"purchase","value":"49.90","currency":"USD","sent_at":"2026-11-03T10:00:00Z","converted_at":"2026-11-03T10:42:00Z","seconds_to_convert":2520}

By phone number (campaigns)

When you do not keep the message id, or the message went out in a portal campaign: POST /v1/conversions {"to":"+573001234567","event":"purchase"} — it goes to the latest tracked message or campaign message sent to that number in the last 7 days (404 no_tracked_message when there is none). GET /v1/conversions lists conversions (limit, starting_after, message_id).

Webhook: event message.converted to your status URL (and to Zapier / Make hooks) with the conversion object.

Versioning

The version is in the path. We add fields, events and optional parameters without a new version, so ignore unknown fields. Breaking changes go to /v2, and /v1 stays available for at least 12 months after that.

Channels: WhatsApp, RCS, Telegram, Viber, voice and email

The same POST /v1/messages sends SMS, WhatsApp, RCS, Telegram and Viber messages, voice calls and emails. Add channel and the content for that channel; without channel everything works exactly as described above for SMS. Every attempt is a normal message (msg_…) with its own status, price, webhooks and report row, so GET /v1/messages, client_ref, callback_url and idempotency work the same on every channel.

curl https://app.ogave.co/v1/messages \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-A123-shipped" \
  -d '{
    "channel": "whatsapp",
    "to": "+573001234567",
    "template": {"name": "order_shipped", "language": "es", "variables": ["Ana", "A123"]},
    "client_ref": "order-A123",
    "fallback": [
      {"channel": "sms", "after": "5m", "text": "Ana, tu pedido A123 fue enviado"},
      {"channel": "voice", "after": "10m", "tts": {"text": "Hola Ana, su pedido fue enviado", "language": "es-MX"}}
    ]
  }'

const res = await fetch("https://app.ogave.co/v1/messages", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "order-A123-shipped",
  },
  body: JSON.stringify({
    channel: "whatsapp",
    to: "+573001234567",
    template: { name: "order_shipped", language: "es", variables: ["Ana", "A123"] },
    client_ref: "order-A123",
    fallback: [
      { channel: "sms", after: "5m", text: "Ana, tu pedido A123 fue enviado" },
      { channel: "voice", after: "10m", tts: { text: "Hola Ana, su pedido fue enviado", language: "es-MX" } },
    ],
  }),
});
const message = await res.json();
if (!res.ok) throw new Error(`${message.error.code}: ${message.error.message}`);
console.log(message.id, message.channel, message.status, message.whatsapp.category, message.price);

import os, requests

res = requests.post(
    "https://app.ogave.co/v1/messages",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}", "Idempotency-Key": "order-A123-shipped"},
    json={
        "channel": "whatsapp",
        "to": "+573001234567",
        "template": {"name": "order_shipped", "language": "es", "variables": ["Ana", "A123"]},
        "client_ref": "order-A123",
        "fallback": [
            {"channel": "sms", "after": "5m", "text": "Ana, tu pedido A123 fue enviado"},
            {"channel": "voice", "after": "10m", "tts": {"text": "Hola Ana, su pedido fue enviado", "language": "es-MX"}},
        ],
    },
    timeout=10,
)
body = res.json()
if not res.ok:
    raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["id"], body["channel"], body["status"], body["price"])

<?php
$ch = curl_init('https://app.ogave.co/v1/messages');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('API_KEY'),
        'Content-Type: application/json',
        'Idempotency-Key: order-A123-shipped',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'channel' => 'whatsapp',
        'to' => '+573001234567',
        'template' => ['name' => 'order_shipped', 'language' => 'es', 'variables' => ['Ana', 'A123']],
        'client_ref' => 'order-A123',
        'fallback' => [
            ['channel' => 'sms', 'after' => '5m', 'text' => 'Ana, tu pedido A123 fue enviado'],
            ['channel' => 'voice', 'after' => '10m', 'tts' => ['text' => 'Hola Ana, su pedido fue enviado', 'language' => 'es-MX']],
        ],
    ]),
]);
$body = json_decode(curl_exec($ch), true);
if (curl_getinfo($ch, CURLINFO_HTTP_CODE) >= 400) {
    throw new RuntimeException("{$body['error']['code']}: {$body['error']['message']}");
}
echo $body['id'], ' ', $body['channel'], ' ', $body['status'], PHP_EOL;

channel

Fields shared by all channels: to, client_ref, callback_url, fallback, and account: the id of one of your connected WhatsApp / voice numbers, RCS agents or bots (portal → Channels). Without it we use your first active number of that channel. On WhatsApp and voice the sender is that number, so from is not used; scheduled_at, validity and flash apply to SMS only.

WhatsApp

24-hour window. Free text and media can only be sent within 24 hours of the contact's last WhatsApp message to you; outside it the request fails with 422 session_closed (send a template instead). Template, session and opt-out checks run before anything is charged.
Opt-out. A contact who replies STOP, BAJA, UNSUBSCRIBE, CANCELAR, PARAR on WhatsApp is opted out of WhatsApp: later sends to that number on WhatsApp fail with opted_out and auto uses SMS.

# Only within 24 h of the customer's last WhatsApp message (otherwise 422 session_closed)
curl https://app.ogave.co/v1/messages -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{"channel": "whatsapp", "to": "+573001234567", "text": "It arrives tomorrow before noon."}'

curl https://app.ogave.co/v1/messages -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{"channel": "whatsapp", "to": "+573001234567",
       "media": {"type": "document", "url": "https://example.com/invoices/A123.pdf", "caption": "Your invoice", "filename": "A123.pdf"}}'

Voice

Give one of them (checked in the order ivr, audio_url, tts); none → missing_content.

# Text to speech
curl https://app.ogave.co/v1/messages -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{"channel": "voice", "to": "+573001234567", "tts": {"text": "Hola, su pedido fue enviado", "language": "es-MX", "voice": "female"}}'

# Play a recording
curl https://app.ogave.co/v1/messages -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{"channel": "voice", "to": "+573001234567", "audio_url": "https://example.com/audio/reminder.mp3"}'

# Run an IVR flow built in the portal, from a specific voice number
curl https://app.ogave.co/v1/messages -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{"channel": "voice", "to": "+573001234567", "ivr": "01jb0c4q8m2n3p4r5s6t7v8w9x", "account": "01jb0bz1k2m3n4p5q6r7s8t9v0"}'

RCS, Telegram and Viber

Every channel is addressed by phone number (to in E.164). Content:

• RCS reaches Android phones with RCS. A phone without RCS ends failed at once (refunded), so a fallback to sms is sent right away instead of after after. A fallback step without text repeats the text of the RCS message.
• Telegram and Viber bots can only write to people who connected their chat. Each contact connects once: send them the bot link (portal → Channels → Telegram / Viber → Bot link, e.g. in an SMS); opening it connects that chat to their phone number. On Telegram, people who write to the bot first are asked to share their phone number with one tap. Sending to a number that is not connected → not_linked (not charged). Telegram has no delivery receipts: accepted by Telegram = delivered. Viber reports delivered and read.
• Replies arrive in the Inbox and as message.inbound webhooks with channel rcs, telegram or viber.

curl -X POST https://app.ogave.co/v1/messages \
  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{"channel": "rcs", "to": "+573001234567", "text": "Your order A123 has shipped", "suggestions": ["Track it", "Talk to us"],
       "fallback": [{"channel": "sms", "after": "2m"}]}'

Email

Verify your sending domain first (portal → Channels › Email → Sending domains: publish the ownership TXT and the DKIM key; SPF and DMARC are recommended). Emails are DKIM-signed with your domain's key. Each request sends one email to one recipient and is priced per email.

curl https://app.ogave.co/v1/messages \
  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{"channel": "email", "to": "ana@example.com", "from": "news@mail.yourshop.com", "from_name": "Your Shop",
       "email_template": "01jexample0template0id00000", "variables": {"first_name": "Ana"}, "category": "marketing"}'

Email statuses. queued → sent (accepted by the mail server) → delivered → read (= opened; a click also counts as opened). failed = bounced: the address is added to your suppression list. The message object has an email object: subject, category, template, from_name, reply_to, opens, clicks, opened_at, clicked_at.

Email webhooks. Besides message.sent, message.delivered, message.read (opened) and message.failed (bounced): message.clicked (with the url clicked), message.complained (marked as spam) and message.unsubscribed. Complaints and unsubscribes add the address to your suppression list and do not change the message status.

Suppression list. Bounced, complained and unsubscribed addresses (and the ones you add in the portal) are never emailed again: sending to them fails with 422 suppressed and is not charged. Remove an address in the portal to email it again.
Price. One price per email (email, any country), charged when it is sent; bounces are not refunded. Test keys are not charged.

Fallback chains

fallback is a list of up to 3 more steps (extra steps are ignored). Each step has channel (sms, whatsapp, voice, email), after and its own content (text, template, media, tts, audio_url, ivr, account, from; for email subject, html, email_template, variables, category). Between email and phone channels the contact's email / phone number is looked up. It works with any first channel, SMS included.

• after: how long to wait for the previous attempt, as 90s, 5m or 1h (30 seconds to 24 hours, default 5m). Other formats → invalid_duration.
• When after has passed, the next step is sent unless the previous attempt succeeded: delivered (SMS, WhatsApp), read (WhatsApp), answered or completed (voice). If a WhatsApp or voice attempt ends in failed, rejected, busy, no_answer or canceled, the next step goes out right away (within a minute) without waiting.
• Each attempt is a separate message with its own id and price, charged when it is sent. It keeps the to, client_ref and callback_url of the first one. An SMS step without text repeats the first message's text, and without from it uses your first active sender ID.
• The API answers with the first message. GET /v1/messages/{id} shows the chain in fallback: previous (the attempt before this one), next (the attempt sent after it) and pending (steps not sent yet, as channel + after_seconds).

POST /v1/messages/quote

Same body as POST /v1/messages. Nothing is sent or charged, and the content is validated as for a real send (template, session, opt-out, account). Answers 200 with the price of the first step and of each fallback step; max_total is the worst case, when every step is sent. Voice steps show the price of the first 60-second block. A step's price is null when that channel is not sold for the destination. Quotes use live prices, also with a test key.

curl https://app.ogave.co/v1/messages/quote -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{"channel": "whatsapp", "to": "+573001234567",
       "template": {"name": "order_shipped", "variables": ["Ana", "A123"]},
       "fallback": [{"channel": "voice", "after": "10m", "tts": "Hola Ana, su pedido fue enviado"}]}'

HTTP/1.1 200 OK
{
  "object": "quote",
  "currency": "USD",
  "max_total": "0.130000",
  "steps": [
    {"channel": "whatsapp", "price": "0.0100"},
    {"channel": "voice", "price": "0.1200", "after_seconds": 600}
  ]
}

For a plain SMS (channel sms or auto resolving to SMS) the quote has only the SMS step and no max_total; fallback steps of an SMS-first chain are not priced. Quote a WhatsApp or voice first step to see the whole chain.

Message object: channel fields

Every message has channel (sms, whatsapp, voice). WhatsApp and voice messages also have one of these objects, and messages in a chain have fallback. On these channels encoding is UTF-8 and segments is 1.

{
  "id": "msg_01m6a2v7k3q9x8r5t4y2w1z0b9",
  "object": "message",
  "mode": "live",
  "channel": "whatsapp",
  "to": "+573001234567",
  "from": "+15550001111",
  "text": "Hi Ana, your order A123 has shipped.",
  "client_ref": "order-A123",
  "status": "sent",
  "error": null,
  "encoding": "UTF-8",
  "segments": 1,
  "flash": false,
  "price": "0.0100",
  "currency": "USD",
  "country": "CO",
  "scheduled_at": null,
  "expires_at": null,
  "callback_url": null,
  "created_at": "2026-10-30T15:02:11Z",
  "submitted_at": "2026-10-30T15:02:12Z",
  "done_at": null,
  "whatsapp": {"type": "template", "template": "order_shipped", "language": "es", "category": "utility"},
  "fallback": {"pending": [{"channel": "sms", "after_seconds": 300}, {"channel": "voice", "after_seconds": 600}]}
}

// A voice attempt that was sent as step 2 of a chain:
{
  "id": "msg_01m6a3c0d4e5f6g7h8j9k0m1n2",
  "channel": "voice",
  "status": "completed",
  "price": "0.1200",
  "voice": {"type": "tts", "duration": 37, "billable_seconds": 60, "digits": null},
  "fallback": {"previous": "msg_01m6a2z9…"},
  "…": "the other message fields"
}

Channel statuses

Besides the SMS statuses (queued, sent, delivered, failed, rejected, canceled also apply), WhatsApp and voice messages use:

Statuses only move forward: a late sent never overwrites delivered.

Channel webhooks

Each status change sends message.<status> to the message's callback_url or your status URL, with the message object (including channel, whatsapp / voice and fallback) in data. New events: message.read, message.ringing, message.answered, message.completed, message.busy, message.no_answer, plus message.sent, message.delivered, message.failed on these channels. They are signed and retried like every webhook.
WhatsApp messages from your contacts arrive as message.inbound at your inbound URL with channel: "whatsapp", from, to (your WhatsApp number), text, media (or null) and received_at. SMS replies keep the shape described in Webhooks (no channel field: treat a missing channel as sms).

POST /your/inbound/url HTTP/1.1
Content-Type: application/json
Webhook-Event: message.inbound

{"id": "evt_01m6a4…", "type": "message.inbound", "mode": "live", "created_at": "2026-10-30T15:20:41Z",
 "data": {"id": "in_8812", "channel": "whatsapp", "from": "+573001234567", "to": "+15550001111",
          "text": "Where is my order?", "media": null, "received_at": "2026-10-30T15:20:41Z"}}

Channel pricing

• WhatsApp: one price per message by template category: wa_marketing, wa_utility, wa_authentication. Session messages (text, media) inside the 24 h window use your wa_service price, which can be zero. A WhatsApp message that ends failed or rejected is refunded.
• Voice: a price per minute (voice_minute) billed in blocks: the first 60 seconds, then every 60 seconds started. The first block is charged when the call is placed and the rest when it ends, on the real duration (voice.billable_seconds). Calls that are not answered (busy, no_answer, failed) are refunded.
• RCS, Telegram, Viber: one price per message (rcs, telegram, viber), refunded when the message ends failed.
• Prices are per destination country and come from your plan; use quote to see them before sending. A channel that is not sold for a country is refused with not_sellable. Test keys are never charged.

POST /v1/journeys/{id}/runs

Starts a run of one of your active journeys (built in the portal → Journeys; {id} is the journey id shown there) for the number to. Body: to * (E.164, e.g. +573001234567) and data: an object of up to 50 key/values (keys: letters, numbers and _, up to 40 chars; values: text or numbers up to 500 chars). The values are available to the journey's steps as variables, e.g. {name} in a step's text. A number has at most one run in progress per journey: starting it again while it runs returns that run. Journeys send real messages, so a live_ key is required.

curl https://app.ogave.co/v1/journeys/01jb0d7e8f9g0h1j2k3m4n5p6q/runs \
  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{"to": "+573001234567", "data": {"name": "Ana", "order": "A123"}}'

HTTP/1.1 201 Created
{"id": 1842, "journey": "01jb0d7e8f9g0h1j2k3m4n5p6q", "phone": "+573001234567", "state": "waiting", "step": "welcome",
 "created_at": "2026-10-30T15:30:02+00:00"}

Messages sent by the run are normal messages: they appear in GET /v1/messages and fire the usual webhooks.

Number masking for calls

Connect two people by phone without showing their numbers — a customer and a driver, a buyer and a seller. Create a session with both numbers; we give you a proxy_number (one of your voice numbers). Either side calls the proxy number and is connected to the other side; both only ever see the proxy number. Calls from any other number, and calls after the session closes or expires, are never connected (the caller hears a short message). One proxy number serves many sessions at the same time: a person is never in two open sessions on the same proxy, so we always know whom to connect.

POST /v1/masking/sessions

curl -X POST https://app.ogave.co/v1/masking/sessions \
  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{"party_a": "+573001234567", "party_b": "+573109876543", "ttl": 7200, "client_ref": "order-A123"}'

201 Created
{"object": "masking_session", "id": "mks_01m6…", "mode": "live", "status": "open", "proxy_number": "+15005550006",
 "party_a": "+573001234567", "party_b": "+573109876543", "label": null, "client_ref": "order-A123", "calls_count": 0,
 "expires_at": "2026-10-31T14:00:00Z", "closed_at": null, "created_at": "2026-10-31T12:00:00Z"}

Send each side the proxy_number (e.g. "Call your driver at +1 500 555 0006").

Get, list, close

• GET /v1/masking/sessions/{id} — the session with its calls (newest first): direction (a_to_b / b_to_a), from, to, status (ringing, completed, busy, no_answer, failed, canceled, rejected), duration_seconds, billable_seconds, price.
• GET /v1/masking/sessions?status=open|closed|expired — up to limit (100) sessions of the key's mode.
• POST /v1/masking/sessions/{id}/close — ends the session now (e.g. when the delivery is done).
• POST /v1/masking/sessions/{id}/simulate-call {"from": "+57…"} — test keys and test voice numbers only: a simulated call (the called party's last digits decide: …0000 failed, …2222 no answer, …3333 busy, otherwise 37 s).

Billing, webhooks, providers

• Each connected call is charged on its talk time at your voice_minute price for the country of the called party, in the same blocks as voice calls. Calls that are not answered or rejected cost nothing. A call is only connected when your balance pays at least one block, and it is cut when the balance or the session runs out (at most 4 h). Test sessions (test key) are never charged.
• When a call ends we send the webhook masking.call.completed (or .busy, .no_answer, .failed, .canceled) to your status URL with the call fields, session_id and client_ref.
• Proxy numbers: your Twilio voice numbers (set the number's Voice webhook to the URL shown in the portal, Channels › Number masking) or test numbers.

Integrations: REST hooks and contacts

For Zapier, Make and your own automations. Full guide, event payloads and the Shopify, WooCommerce, HubSpot and Google Sheets connections: Integrations docs.

REST hooks

Events are delivered like webhooks (same envelope, Webhook-Signature, retries and delivery log), always as a JSON POST. A hook only gets events of its key's mode (test keys: test events). Answer 410 Gone to delete the hook. Up to 50 hooks per account.

Contacts

Errors: invalid_number (not a valid number; national numbers need country), opted_out (the number is on your blacklist), validation_failed with param fields.<TAG> (unknown field or a value that does not fit its type), not_found (unknown list or contact), limit_reached (too many hooks). A contact that unsubscribed is updated but never re-subscribed.

OTP Verify API

Send one-time codes and check them with two calls. We generate the code, store only a keyed hash of it, enforce expiry, attempts and resend rules, and block SMS-pumping before it costs you money.

curl https://app.ogave.co/v1/verify \
  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{"to": "+573001234567", "app_id": "app_01m65mc13skre3jty1rtz8jtqy", "locale": "es", "ip": "203.0.113.7"}'

# then, with the code the user typed:
curl https://app.ogave.co/v1/verify/ver_01m65mc32mhad5g95nbspkpdr4/check \
  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{"code": "482913"}'

const api = (path, body) => fetch(`https://app.ogave.co/v1${path}`, {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify(body),
}).then((r) => r.json());

// 1) send the code (store verification.id in the user's session)
const verification = await api("/verify", { to: "+573001234567", locale: "es", ip: req.ip });
// 2) check what the user typed
const check = await api(`/verify/${verification.id}/check`, { code: userInput });
if (check.result === "approved") { /* log the user in */ }
else if (check.result === "invalid") { /* show "wrong code", check.attempts_remaining left */ }
else { /* expired or max_attempts: offer to start again */ }

import os, requests

API = "https://app.ogave.co/v1"
H = {"Authorization": f"Bearer {os.environ['API_KEY']}"}

v = requests.post(f"{API}/verify", headers=H, json={"to": "+573001234567", "locale": "es", "ip": client_ip}).json()
# ... later, with the code the user typed:
check = requests.post(f"{API}/verify/{v['id']}/check", headers=H, json={"code": user_code}).json()
approved = check.get("result") == "approved"

<?php
function api(string $path, array $body): array {
    $ch = curl_init('https://app.ogave.co/v1' . $path);
    curl_setopt_array($ch, [CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('API_KEY'), 'Content-Type: application/json'],
        CURLOPT_POSTFIELDS => json_encode($body)]);
    return json_decode(curl_exec($ch), true);
}
$v = api('/verify', ['to' => '+573001234567', 'locale' => 'es', 'ip' => $_SERVER['REMOTE_ADDR']]);
$_SESSION['verification_id'] = $v['id'];
// ... later:
$check = api('/verify/' . $_SESSION['verification_id'] . '/check', ['code' => $_POST['code']]);
$approved = ($check['result'] ?? null) === 'approved';

POST /v1/verify

Returns 201 with the verification: id, status: "pending", expires_at, attempts_remaining, price. Starting a new verification for the same number and app cancels the pending one, so only the newest code works.

Several channels, WhatsApp first:

curl https://app.ogave.co/v1/verify -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{"to": "+573001234567", "app_id": "app_01m65mc13skre3jty1rtz8jtqy",
       "channel_order": ["whatsapp", "sms", "voice"], "fallback_after": 45}'

POST /v1/verify/{id}/check

Body {"code": "482913"}. Always 200 with a result:

Checking a closed verification returns 409 verification_closed. Codes are compared in constant time. An approved verification has verified_channel: the channel whose code was entered (sms, whatsapp, voice or email).

Verify by email

With channel: email the code goes by email to to — same app limits, expiry, attempts, resends, pricing model and fraud protection (velocity per address, per email domain, IP, device and account; addresses are stored hashed in the send log). The email is the app's own (email_from = an address of a verified domain of yours, email_subject, email_html with {code}, {app}, {minutes}; PATCH /v1/verify/apps/{id} or Developers › Verify) or a standard one in the verification's locale. In the response to is masked (a***@example.com) and country is null. A suppressed address (bounce, complaint, unsubscribe) is refused at once with 422 suppressed, nothing charged.

Email fallback

Switch on email_fallback in the Verify app and send email with POST /v1/verify. If the code is not verified within email_fallback_after seconds (app setting, 30–600, default 60), we also send a code by email, from the platform's email channel, in the verification's locale. If the SMS fails before that, the email goes out at once instead of the verification failing. The email has its own code; both codes work until the verification closes, and verified_channel tells which one was used. The response shows email_fallback (masked address, due_at, sent_at). Once closed, the address is kept masked and the email copy of the code is redacted. The order is always SMS (or your channel_order) first, email last. Voice as a fallback after email is not available yet.

Resend, cancel, get, list

POST /v1/verify/{id}/resend sends a new code (the previous one stops working) and restarts the expiry. It needs the app's cooldown to have passed (429 resend_cooldown with Retry-After) and allows up to the app's max_resends (429 max_resends). Failed attempts are not reset by a resend.
POST /v1/verify/{id}/cancel · GET /v1/verify/{id} · GET /v1/verify?status=approved&to=…&limit=…&starting_after=…

Verify apps

One app per product or brand: name (used as {app_name}), code_length, code_type, expiry_seconds, max_attempts (1–10), resend_cooldown_seconds, max_resends, sender_id, template, default_locale, allowed_countries / denied_countries (ISO codes; an allow list wins), test_numbers, fraud_limits, flash (send codes as Flash SMS), email_fallback and email_fallback_after. Manage them in the portal or with GET/POST /v1/verify/apps, GET/PATCH /v1/verify/apps/{id}.

Fraud protection (SMS pumping)

Before any code is sent we check, in order: the app's country rules, active blocks, then velocity (sliding windows, counted separately for live and test keys):

The prefix is the number without its last 4 digits. Burst detection: when one prefix gets 20+ codes within 5 minutes and fewer than 10% of them are approved, the prefix is blocked for 60 minutes (403 prefix_blocked), because real users approve their codes and pumping traffic doesn't. Other errors: country_not_allowed, number_blocked, ip_blocked. Limits can be tuned per app (fraud_limits).

Testing

With a test_ key nothing is sent or charged and the code is always 123456 (the first n digits of 1234567890 for longer codes). For app-store reviewers and QA on live keys, add test_numbers to the app: those numbers get your fixed code, never receive an SMS, are never charged and skip fraud limits.

Okta and Auth0

Okta and Auth0 can send their own one-time codes through your Verify app (sender, template, language, fraud protection) without code: Okta Telephony Inline Hook (POST /v1/verify/connectors/okta) and Auth0 custom phone provider (POST /v1/verify/connectors/auth0). Use a key with only the verify permission. These verifications have source okta / auth0; the platform checks the code itself.

Webhooks and pricing

Events to your status URL: verification.pending, verification.approved, verification.expired, verification.max_attempts, verification.canceled, verification.failed (the SMS could not be delivered to the network), signed like all webhooks. The code is never included in any response or webhook, and the SMS appears in /v1/messages with the code masked (••••••); our copy for the network is redacted as soon as the verification closes.

Pricing depends on your plan (the verification's pricing field; the Verify page in the portal shows yours):

In both models, starting a verification that is blocked, checking codes, canceling and test numbers are free. The verification's price shows the total (with per_success: the fee once approved, otherwise 0), and each message also appears in GET /v1/messages with client_ref: "verify:<id>".

Fraud protection (SMS pumping)

Artificially inflated traffic is bots requesting codes or messages to premium or foreign numbers so that someone else earns from the traffic. These checks run on live traffic of Verify, /v1/messages and portal sends, are on by default, and every refusal is logged with what it would have cost (portal: Developers › Fraud protection).

Send device_id (a stable fingerprint of your user's device, ≤ 64 visible characters) with POST /v1/verify to enable the per-device limit. Test keys are never limited by these checks.