heysteff for developers
The WhatsApp, Instagram, Messenger, SMS and email API, with an inbox for your team.
One endpoint to send, signed webhooks to receive, and your store data in the same place. Your code replies and, when a person is needed, your team picks up the conversation on the web or on their phone.
Try it with an sk_test_ key and the shared sandbox number, without connecting a number of your own.
curl https://app.heysteff.com/api/v1/messages \
-H "Authorization: Bearer $HEYSTEFF_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: pedido-1042-en-camino" \
-d '{
"channel": "whatsapp_cloud",
"to": "+56912345678",
"content": "Hi Ana, your order #1042 is on its way."
}'import { Heysteff } from '@heysteff/sdk';
const heysteff = new Heysteff(); // lee HEYSTEFF_API_KEY
const message = await heysteff.messages.send({
channel: 'whatsapp_cloud',
to: '+56912345678',
content: 'Hi Ana, your order #1042 is on its way.',
});
console.log(message.id, message.status);npm install -g @heysteff/cli
heysteff login
heysteff messages send --channel whatsapp_cloud \
--to +56912345678 \
--text "Hi Ana, your order #1042 is on its way."POST /v1/messages201 Created · "status": "pending"
- Baseapp.heysteff.com/api/v1
- AuthBearer sk_live_ · sk_test_
- SpecOpenAPI 3.1
- Rate limit120 requests / 60 s
- WebhooksHMAC-SHA256 · 6 attempts
Bring your own AI
Your model answers. We bring the channel and the inbox.
Connect the model you already use without writing a Meta integration. heysteff delivers every message to your server and sends whatever your model replies.
The customer writes
On WhatsApp, Instagram, Messenger, SMS or email. Every channel lands in the same contact conversation.
We notify you
A signed POST to your server with the
message:receivedevent. If your server does not answer, we retry with growing waits.Your model decides
Read the history with
GET /v1/conversations/{id}/messagesand reply withPOST /v1/messages, with anIdempotency-Keyso you never answer twice.A person takes over
When your model should stop, your team replies from the heysteff inbox, on the web or in the mobile app, with the whole history in view.
When your model does not know, POST /v1/conversations/{id}/escalate hands the conversation to a person in the inbox and pauses the bot; the following events arrive with bot_paused: true. POST /v1/conversations/{id}/bot and /resolve give it back to your AI. The Bring your own AI guide has the full flow, and Coding agents a prompt to build it with your coding agent.
Or use the heysteff agent
An AI agent on every plan, paid for with your own key.
If you would rather not run a model, turn on the agent: it replies on all your channels with your instructions and your context files, checks your backend with custom tools and hands the conversation to your team when it should.
- Your key, your costSave your Anthropic, OpenAI, DeepSeek or OpenRouter key and the provider bills you for tokens directly. heysteff adds nothing on top.
- Trial quotaWithout a key, the agent replies with the heysteff key: 200 replies a month on Developer Free, 2,000 on Developer and 20,000 on Developer Platform.
- Custom toolsThe agent calls your API mid-conversation to look up an order, stock or a calendar: 2 on Developer Free, 10 on Developer and no cap on Developer Platform.
- On where you want itPer workspace, per channel, per customer of your SaaS or per conversation, from the console or with
PATCH /v1/agent. - Agent webhooks
agent.replied,agent.handoffandagent.failedtell you what it answered, when it handed the conversation to a person and why it could not reply. - InsightsOn Developer and Developer Platform you see what the agent could not answer and which customers left frustrated: in the console, with
GET /v1/insightsor with the weeklyinsight.detectedwebhook.
The AI agent guide covers turning it on, models and their prices, errors and webhooks.
Already solved
What you do not have to build
The parts that eat weeks when you wire up the Meta Cloud API yourself are already done.
- An inbox for peopleYour team reads and answers every conversation on the web and in the Android and iOS app, with internal notes, owners and the full history.
- WhatsApp templatesCreate and review them in the dashboard, list them with
GET /v1/templatesand send them withcontent_type: "template"outside the 24-hour window. - Opt-outsAnyone who replies STOP, BAJA or CANCELAR stops getting SMS from your number, and WhatsApp opt-outs are recorded for your campaigns.
- Anti-ban pacingWith WhatsApp connected by QR, every send goes through per-number pacing that spaces messages out so they do not trigger a restriction.
- Webhooks that do not get lostHMAC-SHA256 signatures, 6 attempts with growing waits, a log of every delivery and retries with
POST /v1/webhook-deliveries/{id}/retry. - Shopify and salesWith the store connected, cart recovery, review requests and attributed sales work in the same workspace and arrive as events at your webhook.
Tools
From your terminal, your code or your AI agent.
REST API
JSON, one API key per integration with scopes, idempotent writes and cursor pagination. The OpenAPI 3.1 spec generates a client in any language.
SDK
@heysteff/sdk for TypeScript, with no dependencies: it runs on Node 20+, Deno, Bun and Cloudflare Workers. It retries with the same idempotency key and verifies webhooks.
CLI
The heysteff command: log in with your key, send messages, list conversations and templates, and test your webhook on localhost with a signed event.
MCP
A remote MCP server with OAuth so Claude Code, Codex or Cursor can configure your workspace: agent, channels, flows and campaigns. It signs in as you, never with an API key.
Sandbox
An sk_test_ key sends through the shared heysteff number to the phones you join to the sandbox, up to 5. It never writes to a customer.
Templates
Start from an omnichannel inbox in Next.js, an AI agent that answers with Claude, or a minimal send. MIT code, your key lands in .env.local, and the inbox deploys to Vercel in one click.
Open source
Start from our GitHub.
MIT-licensed templates and integrations. Fork, add your API key and go.
Omnichannel inbox
A Next.js inbox for WhatsApp, Instagram, Messenger, SMS and email. It only needs your API key and deploys to Vercel in one click.
AI agent starter
A Claude agent that answers on any channel and hands off to a person when needed.
Coding agent plugin
MCP, skills and safety rules for Claude Code, Cursor and Codex.
Skills
Integrate, automate and observe heysteff from your coding agent.
n8n nodes
A trigger that creates its own webhook, plus omnichannel sending from your workflows.
Comparison
heysteff or the Meta Cloud API directly
If all you need is to send WhatsApp templates from a system, the Cloud API on its own may be enough. This is what changes once there are people, more channels and a store.
| Meta Cloud API directly | With heysteff | |
|---|---|---|
| Number setup | You create the app, the business portfolio and the WhatsApp Business account, and register the number yourself. | Meta guided signup from the dashboard, or WhatsApp by QR. |
| Channels | WhatsApp only. Instagram and Messenger are other Meta APIs; SMS and email, other providers. | WhatsApp, Instagram, Messenger, SMS and email with the same POST /v1/messages. |
| Receiving messages | A Meta webhook with a different format per product. | One message:received event for every channel, signed, with a delivery log. |
| People in the conversation | You build the inbox. | Included, on the web and in the mobile app. |
| Commerce data | Out of scope. | Shopify, carts, reviews and attributed sales in the same workspace. |
| Message costs | Meta bills your WhatsApp Business account. | Same: Meta bills your account directly and heysteff adds no markup. You pay your heysteff plan on top. |
| API surface | The full WhatsApp Graph API. | The heysteff v1 API. Anything not in the reference cannot be done through the API yet. |
Start free with the sandbox.
Create your account, generate an sk_test_ key and send your first WhatsApp from your terminal. Developer plans are on the pricing page.
Questions
Technical questions
Do I need my own number to test?
No. With an sk_test_ key, messages go out through the shared sandbox number, only to the phones you join to your workspace. When you want to write to customers, connect your number in Settings → Channels and use an sk_live_ key.
Can I use my own AI model?
Yes. Your server receives every message with the message:received webhook, passes it to your model and replies with POST /v1/messages. A developer workspace starts with the heysteff agent off, so two bots never answer.
How much does the heysteff AI agent cost?
It comes with every plan. With your own provider key you pay that provider for tokens directly, with no markup from us. Without a key, you use the plan’s trial quota; once it runs out, the agent stops replying and the agent.failed webhook arrives with ai_quota_exhausted. Details in AI agent.
What happens outside the WhatsApp 24-hour window?
WhatsApp only accepts free text within 24 hours of the customer’s last message. Outside that window you send a Meta-approved template, with the same endpoint and content_type: "template".
What are the API limits?
Each API key allows 120 requests per 60-second window; past that it returns 429 rate_limited. Plan limits, such as messages per month, return 402 plan_limit_exceeded. Details are in Errors and limits.
How do I avoid sending a message twice?
Send an Idempotency-Key header with one key per logical operation. If you repeat the request with the same key, you get the same response and no second message goes out. The SDK does it for you on every retry.
What if my server goes down?
Each delivery is retried after 1, 2, 4, 8 and 16 minutes; after the sixth failed attempt it is marked as failed. List them with GET /v1/webhooks/{id}/deliveries, resend them with POST /v1/webhook-deliveries/{id}/retry and catch up on what happened with GET /v1/events.
How much does Meta charge for messages?
With WhatsApp on the official API, Meta bills its messages directly to your business’s WhatsApp Business account and heysteff adds no markup. Developer plans are on the pricing page.