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.
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!" }
}'// 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
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
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 messagecurl -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
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
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.
Authorization: Bearer sk_live_9f2c...
Content-Type: application/json
Idempotency-Key: order-12345-shippedFour 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.
textInside an open window
Free-form text. Only valid while a 24-hour conversation window with that contact is open, which a customer message opens.
templateTo 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 · videoInside an open window
Media by URL or by uploaded id, with an optional caption. Size and format limits follow what WhatsApp accepts.
interactiveInside 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.
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.
| Event | Meaning |
|---|---|
| message.sent | Accepted and handed to the channel. |
| message.delivered | Reached the recipient's device. |
| message.read | Opened by the recipient, where the channel reports it. |
| message.failed | Terminal failure, with a reason code attached. |
| message.received | An inbound message from a customer. |
| conversation.opened | A customer message opened a 24-hour service window. |
| flow.step_completed | A node in a flow finished, with its result. |
| flow.handoff | A run stopped and assigned the conversation to a person. |
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": "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
}
}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.
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.
| Status | Type | What it means | Retry |
|---|---|---|---|
| 400 | invalid_request_error | The payload is wrong: a missing field, a bad type, a template variable count that does not match. Fix the call. | No |
| 401 | authentication_error | Missing, malformed, or revoked key. Also what you get when a live key is pointed at a test resource. | No |
| 403 | permission_error | The key is valid but its scope does not cover this call, or the number is not one your account owns. | No |
| 404 | not_found_error | No such message, conversation, or contact. Usually an id from another environment. | No |
| 422 | channel_policy_error | The channel refused it: an unapproved template, a closed conversation window, or a contact who opted out. | No |
| 429 | rate_limit_error | Throttled and not processed. Honour Retry-After and send it again. | Yes |
| 5xx | api_error | Something 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.
Node.js & TypeScript
Available@techardentlabs/vive-sdk
View on GitHub(opens in a new tab)npm install @techardentlabs/vive-sdkPython
Availablevive
View on GitHub(opens in a new tab)pip install viveGo
Availablegithub.com/techardentlabs/vive-go
View on GitHub(opens in a new tab)go get github.com/techardentlabs/vive-goPHP
Source availablevive/sdk
Not on a package registry yet. Install from the repository.
View on GitHub(opens in a new tab)Ruby
Source availablevive
Not on a package registry yet. Install from the repository.
View on GitHub(opens in a new tab)Any other language
AvailableREST API
Plain HTTPS and JSON with a bearer token. Nothing about the API needs a client library.
Jump to quick start
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.