Echoo API

One API for every Echoo service. The first service is OTP: one-time verification codes delivered over WhatsApp.

One address, one kind of key, one error shape for every service. A key belongs to ONE profile (one website or app of the customer): the key alone tells which profile, so requests never name the profile. Live keys start with ek_live_, test keys with ek_test_ (a test key never sends a message; see Test mode).

Base URL: https://api.echoo.services

Quick start

1. Make a key. In the Echoo dashboard, open your profile and make an API key. Start with a test key (ek_test_…): it sends nothing and the code is always 000000. Put it in your server's environment as ECHOO_API_KEY.
2. Send a code when a person types their phone number. Keep the id of the answer with their sign-up or login attempt.
   cURLJavaScriptPythonPHPCopy

   curl -X POST https://api.echoo.services/v1/otp/send \
     -H "Authorization: Bearer $ECHOO_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"to":"+9647701234567","locale":"ar"}'

3. Check the code the person typed. Continue only when valid is true.
   cURLJavaScriptPythonPHPCopy

   curl -X POST https://api.echoo.services/v1/otp/verify \
     -H "Authorization: Bearer $ECHOO_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"id":"otp_req_01JD8X2W3Y4Z5A6B7C8D9E0F1G","code":"482913"}'

Keys

Authorization: Bearer ek_live_... (or ek_test_...). A key belongs to one profile and carries scopes (otp:send, otp:verify, otp:read). It is shown once when made; Echoo keeps only a hash of it.

Send it on every call as Authorization: Bearer ek_live_…. Call the API from your server only: a key in a web page or a mobile app can be copied. If a key leaks, revoke it in the dashboard and make a new one.

For AI agents

Also at /llms.txt, and the full machine-readable contract at /openapi.json.

Endpoints

curl -X POST https://api.echoo.services/v1/otp/send \
  -H "Authorization: Bearer $ECHOO_API_KEY" \
  -H "Idempotency-Key: 3f2b8c1e-9d4a-4f6b-8a2e-5c7d9e1f0a3b" \
  -H "Content-Type: application/json" \
  -d '{"to":"9647701234567","locale":"ar","code_length":6,"ttl_seconds":300,"reference":"signup-58213"}'

const res = await fetch("https://api.echoo.services/v1/otp/send", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.ECHOO_API_KEY}`, "Content-Type": "application/json", "Idempotency-Key": "3f2b8c1e-9d4a-4f6b-8a2e-5c7d9e1f0a3b" },
  body: JSON.stringify({ to: "9647701234567", locale: "ar", code_length: 6, ttl_seconds: 300, reference: "signup-58213" }),
});
const data = await res.json();

import os, requests

res = requests.post(
    "https://api.echoo.services/v1/otp/send",
    headers={"Authorization": f"Bearer {os.environ['ECHOO_API_KEY']}", "Idempotency-Key": "3f2b8c1e-9d4a-4f6b-8a2e-5c7d9e1f0a3b"},
    json={"to": "9647701234567", "locale": "ar", "code_length": 6, "ttl_seconds": 300, "reference": "signup-58213"},
    timeout=15,
)
data = res.json()

<?php
$ch = curl_init("https://api.echoo.services/v1/otp/send");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 15,
    CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("ECHOO_API_KEY"), "Content-Type: application/json", "Idempotency-Key: 3f2b8c1e-9d4a-4f6b-8a2e-5c7d9e1f0a3b"],
    CURLOPT_POSTFIELDS => json_encode(["to" => "9647701234567", "locale" => "ar", "code_length" => 6, "ttl_seconds" => 300, "reference" => "signup-58213"]),
]);
$data = json_decode(curl_exec($ch), true);

{
  "id": "otp_req_01JD8X2W3Y4Z5A6B7C8D9E0F1G",
  "status": "queued",
  "channel": "whatsapp",
  "to_masked": "964*******67",
  "created_at": "2026-11-14T10:00:00Z",
  "expires_at": "2026-11-14T10:05:00Z",
  "verified": false,
  "reference": "signup-58213"
}

curl -X POST https://api.echoo.services/v1/otp/verify \
  -H "Authorization: Bearer $ECHOO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":"otp_req_01JD8X2W3Y4Z5A6B7C8D9E0F1G","code":"482913"}'

const res = await fetch("https://api.echoo.services/v1/otp/verify", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.ECHOO_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({ id: "otp_req_01JD8X2W3Y4Z5A6B7C8D9E0F1G", code: "482913" }),
});
const data = await res.json();

import os, requests

res = requests.post(
    "https://api.echoo.services/v1/otp/verify",
    headers={"Authorization": f"Bearer {os.environ['ECHOO_API_KEY']}"},
    json={"id": "otp_req_01JD8X2W3Y4Z5A6B7C8D9E0F1G", "code": "482913"},
    timeout=15,
)
data = res.json()

<?php
$ch = curl_init("https://api.echoo.services/v1/otp/verify");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 15,
    CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("ECHOO_API_KEY"), "Content-Type: application/json"],
    CURLOPT_POSTFIELDS => json_encode(["id" => "otp_req_01JD8X2W3Y4Z5A6B7C8D9E0F1G", "code" => "482913"]),
]);
$data = json_decode(curl_exec($ch), true);

{
  "id": "otp_req_01JD8X2W3Y4Z5A6B7C8D9E0F1G",
  "valid": true
}

{
  "id": "otp_req_01JD8X2W3Y4Z5A6B7C8D9E0F1G",
  "valid": false,
  "reason": "invalid",
  "attempts_left": 3
}

curl https://api.echoo.services/v1/otp/requests/otp_req_01JD8X2W3Y4Z5A6B7C8D9E0F1G \
  -H "Authorization: Bearer $ECHOO_API_KEY"

const res = await fetch("https://api.echoo.services/v1/otp/requests/otp_req_01JD8X2W3Y4Z5A6B7C8D9E0F1G", {
  method: "GET",
  headers: { Authorization: `Bearer ${process.env.ECHOO_API_KEY}` },
});
const data = await res.json();

import os, requests

res = requests.get(
    "https://api.echoo.services/v1/otp/requests/otp_req_01JD8X2W3Y4Z5A6B7C8D9E0F1G",
    headers={"Authorization": f"Bearer {os.environ['ECHOO_API_KEY']}"},
    timeout=15,
)
data = res.json()

<?php
$ch = curl_init("https://api.echoo.services/v1/otp/requests/otp_req_01JD8X2W3Y4Z5A6B7C8D9E0F1G");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 15,
    CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("ECHOO_API_KEY")],
]);
$data = json_decode(curl_exec($ch), true);

Objects

OtpRequest

VerifyResult

WebhookEvent

Errors

Every error has the same shape. Write your program against code, never against the message. When retry_after is there (also as the Retry-After header), wait that many seconds before trying again.

{
  "error": {
    "code": "too_soon",
    "message": "A code was just sent to this number. Wait before asking again.",
    "retry_after": 30,
    "request_id": "req_01JD8X2W3Y4Z5A6B7C8D9E0F1G"
  }
}

Webhooks

Add an address in the Echoo dashboard and Echoo POSTs these events to it. Answer with any 2XX within 10 seconds. A repeated delivery carries the same event id: ignore ids you already handled.

The body is a WebhookEvent. Check that every delivery is from Echoo before you trust it: Echoo-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of '<t>.<raw body>' with the endpoint's signing secret>. Refuse it if the signature does not match or t is older than 5 minutes. Keep the secret in your server's environment (for example ECHOO_WEBHOOK_SECRET), and read the raw body before parsing it.

import crypto from "node:crypto";

// rawBody: the request body exactly as received (a string), before any JSON parsing.
export function isFromEchoo(rawBody, header, secret) {
  const parts = Object.fromEntries(String(header).split(",").map((p) => p.split("=", 2)));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false; // older than 5 minutes: refuse
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  const given = String(parts.v1 ?? "");
  return given.length === expected.length && crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected));
}

import hashlib, hmac, time

# raw_body: the request body exactly as received (bytes), before any JSON parsing.
def is_from_echoo(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
    t = int(parts.get("t", "0") or 0)
    if not t or abs(time.time() - t) > 300:  # older than 5 minutes: refuse
        return False
    expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))

<?php
// $rawBody: file_get_contents("php://input"), before any JSON decoding.
function is_from_echoo(string $rawBody, string $header, string $secret): bool {
    $parts = [];
    foreach (explode(",", $header) as $p) {
        [$k, $v] = array_pad(explode("=", $p, 2), 2, "");
        $parts[$k] = $v;
    }
    $t = (int)($parts["t"] ?? 0);
    if (!$t || abs(time() - $t) > 300) return false; // older than 5 minutes: refuse
    $expected = hash_hmac("sha256", $t . "." . $rawBody, $secret);
    return hash_equals($expected, $parts["v1"] ?? "");
}

Test mode

Keys that start with ek_test_.... Nothing is sent and nothing counts against limits or plans. Every send answers 202 and the request becomes 'sent' within a second. The code for any test request is 000000; any other code is 'invalid'. Webhooks are sent as for live requests, with data.test = true.

Limits

• Per key: 60 requests a minute.
• Per phone number: one code every 30 seconds and 3 an hour.
• Body: at most 4096 bytes.

Starting values; the service may lower them for safety, and they may change after measurement.

Good practice

• Protect your form. Put a human check and a per-visitor limit on the form that asks for a code, so nobody can use it to flood phone numbers (and your plan).
• Keep the id on your server. Store the request id in the server session of the attempt; never trust an id sent back by the browser for another person.
• Never handle the code yourself. Do not log it, store it or send it to the page: Echoo makes it, sends it and checks it.
• Retry safely. Send an Idempotency-Key with each send and reuse it when you retry, so a retry never sends a second code.
• Respect the wait. On 429 and 503, wait retry_after seconds; show the person a short message rather than retrying in a loop.
• One key per place. Use separate keys for each server or app, with only the scopes it needs, so one can be revoked without stopping the others.

Versioning

v1 never changes in a breaking way: fields and error codes may be ADDED, never removed or renamed. A breaking change becomes /v2, announced in advance, and both run side by side for a period.