Skip to main content
RoutMe

Plain HTTPS. JSON in, JSON out.

Official clients for Node, Python, Go, PHP, and Ruby wrap a REST API you could just as easily call by hand. You authenticate with a bearer token, post a message, and receive events on a URL you own. The interesting part is not the API surface, it is what you connect the agent to.

POST /v1/messages
curl -X POST https://api.routme.io/v1/messages \
  -H "Authorization: Bearer $VIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155550123",
    "type": "text",
    "text": { "body": "Hello from RoutMe!" }
  }'
webhook event
// POST https://your-app.com/webhooks/vive
{
  "event": "message.delivered",
  "message_id": "wamid.xxx",
  "conversation_id": "conv_01H...",
  "to": "+14155550123",
  "timestamp": 1718600000
}
Message types, one endpoint
10
Webhook events, signed
8
Official SDKs
5
Typed errors you can branch on
7

Quick start

Four steps from an empty account to an agent that answers a real question. The first three are the same as any messaging API. The fourth is the one that changes the replies.

  1. 1

    Get your API key

    Keys are created per environment from the dashboard once your account is provisioned. Use a test key against your own number before anything touches a customer.

    Get your API key
    # Keys are managed in the dashboard
    # https://app.routme.io/settings/api-keys
    
    export VIVE_API_KEY="sk_live_..."
  2. 2

    Send a message

    One authenticated POST. Inside an open 24-hour conversation window you can send free-form text; outside it, you send an approved template instead.

    Send a message
    curl -X POST https://api.routme.io/v1/messages \
      -H "Authorization: Bearer $VIVE_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "to": "+14155550123",
        "type": "text",
        "text": { "body": "Hello from RoutMe!" }
      }'
  3. 3

    Receive webhooks

    Register a URL and you get delivery state, read receipts, and inbound messages as they happen. Respond 2xx quickly and do the real work off the request thread.

    Receive webhooks
    // POST https://your-app.com/webhooks/vive
    {
      "event": "message.delivered",
      "message_id": "wamid.xxx",
      "conversation_id": "conv_01H...",
      "to": "+14155550123",
      "timestamp": 1718600000
    }
  4. 4

    Give the agent something to read

    Sending is the easy half. Attach a tool to the agent node so an inbound question can be answered from your own records instead of a canned reply.

    Give the agent something to read
    {
      "tool": "orders.lookup",
      "transport": "http",
      "url": "https://your-app.com/internal/orders",
      "auth": { "type": "bearer", "secret_ref": "ORDERS_TOKEN" }
    }

One header, scoped narrowly

Authentication is deliberately boring. What is worth thinking about is how much a single key is allowed to do, and how quickly you could turn it off.

Bearer keys, sent as a header
Every request carries Authorization: Bearer with your key. Keys never go in a query string, because query strings end up in logs, proxies, and browser history.
One key per environment
Test and live keys are separate credentials against separate data. A test key cannot send to a number you have not verified, which is what makes it safe to hand to CI.
Scopes, not all-or-nothing
A key that only needs to send does not need to read conversations. Narrow the scope at creation and a leaked key is a smaller problem.
Rotate without a maintenance window
Create the replacement, deploy it, then revoke the old one. Both are valid in between, so rotation is a deploy rather than an outage.
request headers
Authorization: Bearer sk_live_9f2c...
Content-Type: application/json
Idempotency-Key: order-12345-shipped

Four message types, one endpoint

Everything goes to POST /v1/messages and differs only by the type field. The rule that trips people up is not in the API, it is in the window: you can reply freely for 24 hours after a customer writes, and you need an approved template to start the conversation yourself.

  • text

    Inside an open window

    Free-form text. Only valid while a 24-hour conversation window with that contact is open, which a customer message opens.

  • template

    To open a window

    A pre-approved template with variables. This is the only way to message someone first, and the category you register it under decides the rate you pay.

  • image · document · audio · video

    Inside an open window

    Media by URL or by uploaded id, with an optional caption. Size and format limits follow what WhatsApp accepts.

  • interactive

    Inside an open window

    Reply buttons and list menus. Worth reaching for whenever the answer is one of a few known options, since a tap cannot be misspelled.

POST /v1/messages
curl -X POST https://api.routme.io/v1/messages \
  -H "Authorization: Bearer $VIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ORD-12345-confirm" \
  -d '{
    "to": "+14155550123",
    "type": "template",
    "template": {
      "name": "order_confirmation",
      "language": "en",
      "components": [{
        "type": "body",
        "parameters": [{ "type": "text", "text": "ORD-12345" }]
      }]
    }
  }'

Everything that happens, on a URL you own

Delivery state, inbound messages, and flow progress all arrive the same way. Verify the signature, acknowledge fast, and process afterwards.

EventMeaning
message.sentAccepted and handed to the channel.
message.deliveredReached the recipient's device.
message.readOpened by the recipient, where the channel reports it.
message.failedTerminal failure, with a reason code attached.
message.receivedAn inbound message from a customer.
conversation.openedA customer message opened a 24-hour service window.
flow.step_completedA node in a flow finished, with its result.
flow.handoffA run stopped and assigned the conversation to a person.
verify the signature
const crypto = require("crypto");

function verify(rawBody, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}
Acknowledge, then work
Return 2xx before you write to your database or call another service. A slow handler looks identical to a broken one from our side.
Expect duplicates
Retries mean an event can arrive twice. Key your handler on the event id and make it safe to run again, rather than assuming exactly-once delivery.
Order is not guaranteed
A read receipt can land before the delivered event it follows. Use the timestamp to order state, not arrival.
Failures back off
Non-2xx responses are retried with growing intervals. Persistent failure pauses the endpoint and surfaces it in the dashboard rather than silently dropping.

The part that makes replies worth reading

An agent with no tools is a paraphrasing machine. Attach an MCP server or a plain HTTP endpoint and it can answer "where is my order" with an actual answer.

Expose only what the turn needs
List the specific tools an agent may call. A support agent that never issues refunds should not be holding a refund tool to begin with.
Credentials stay on your side
Tools are referenced by a secret you store, and calls are made against your endpoint. We do not need a copy of your database to answer a question about it.
Read-only by default
Start with lookups. Promote a tool to a write only once you can point at the flow logic that guards it.
Timeouts are a product decision
A tool that takes eight seconds turns a fast conversation into a slow one. Set a budget, and give the flow a branch for what happens when it is exceeded.
agent tool configuration
{
  "agent": "support",
  "mcp_servers": [
    {
      "name": "orders",
      "url": "https://mcp.your-app.com/orders",
      "auth": { "type": "bearer", "secret_ref": "ORDERS_TOKEN" },
      "expose": ["orders.lookup", "shipping.track"]
    }
  ],
  "policy": {
    "read_only": true,
    "timeout_ms": 4000
  }
}
See how a flow uses this

Throttling you can read off the response

Limits apply per account and vary with your channel tier, so the exact numbers live in the API reference alongside your own account. What does not vary is how a limit tells you about itself.

Every response carries the budget
Remaining requests and the reset time come back on each call, so you can pace a batch without discovering the ceiling by hitting it.
429 means wait, not fail
A throttled request was never processed. Honour Retry-After, back off with jitter, and it will go through.
Two separate ceilings
API throughput is ours. Messaging throughput is the channel's, and on WhatsApp it also depends on your quality rating and tier.
Queue rather than spray
For campaigns, feed a queue at a steady rate. Bursts get throttled and, on messaging channels, sustained bursts affect the rating that sets your tier.
429 Too Many Requests
HTTP/1.1 429 Too Many Requests
Retry-After: 2
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1718600120

{
  "error": {
    "type": "rate_limit_error",
    "message": "Request rate exceeded. Retry after 2s."
  }
}

Which failures are worth retrying

Errors come back with a type as well as a status, so your handler can branch on the type rather than on a string match against the message.

StatusTypeWhat it meansRetry
400invalid_request_errorThe payload is wrong: a missing field, a bad type, a template variable count that does not match. Fix the call.No
401authentication_errorMissing, malformed, or revoked key. Also what you get when a live key is pointed at a test resource.No
403permission_errorThe key is valid but its scope does not cover this call, or the number is not one your account owns.No
404not_found_errorNo such message, conversation, or contact. Usually an id from another environment.No
422channel_policy_errorThe channel refused it: an unapproved template, a closed conversation window, or a contact who opted out.No
429rate_limit_errorThrottled and not processed. Honour Retry-After and send it again.Yes
5xxapi_errorSomething on our side. Retry with backoff and the same idempotency key.Yes

SDKs and libraries

Official clients wrap the same REST API in idiomatic types, retries, and webhook signature verification. Every one of them covers all ten message types and adds no third-party dependencies. The REST API still works with any language.

Stuck on something specific?

Send the request id from the failing call and we can look it up directly. That is usually faster than describing the symptom.