canonical: https://jentic.com/apis/heyy.io/heyy

# Heyy API

The Heyy API drives an omnichannel messaging platform that unifies WhatsApp, web chat, and other conversational channels. Across 37 endpoints, agents manage contacts and their attributes, run broadcast campaigns with recipient lists and scheduled starts, send WhatsApp messages, configure webhooks for incoming events, manage labels and custom attributes, trigger automations, and query chats and channels. Authentication uses a Bearer JWT issued from the Heyy console.

## For AI agents

Manage Heyy contacts, broadcasts, WhatsApp messaging, automations, and webhooks across an omnichannel inbox using Bearer JWT authentication.

## Scope

Does not handle voice calls, SMS without WhatsApp, or social media publishing - use for omnichannel messaging, broadcasts, and contact management only.

## Capabilities

- Create, update, and delete contacts and attach custom attributes via `/contacts/{contactId}/attributes`
- Run broadcast campaigns by creating a broadcast, adding recipients, and triggering POST /{channelId}/broadcasts/{broadcastId}/start
- Send WhatsApp messages from a connected channel via POST /{channelId}/whatsapp_messages/send
- Configure webhooks to receive inbound message and delivery events with create, update, and delete operations
- Trigger named automations through POST `/automations/{automationId}/trigger` to run multi-step flows on demand
- Manage chats and channels - list active chats, update chat state, and inspect connected channels
- Maintain shared labels and message templates that broadcasts and chat agents can reuse

## Use cases

### WhatsApp Broadcast Campaigns

Marketing teams build a recipient list, create a broadcast on a WhatsApp channel via POST /{channelId}/broadcasts, attach contacts with POST /{channelId}/broadcasts/{broadcastId}/recipients, and start delivery with POST /{channelId}/broadcasts/{broadcastId}/start. The API tracks recipients separately so you can pause, resume, or audit who received a message without re-creating the broadcast.

Example prompt: Create a broadcast on channel WA-001 with template welcome_v3, add 500 contacts via the recipients endpoint, then call POST /{channelId}/broadcasts/{broadcastId}/start.

### Conversational CRM Sync

Sync contacts and their attributes between Heyy and an internal CRM by polling GET /contacts and pushing updates with PUT `/contacts/{contactId}` and POST `/contacts/{contactId}/attributes.` Labels keep segmentation consistent across the inbox and your CRM, so support agents see the same context as marketing automations.

Example prompt: For each new CRM lead, call POST /contacts with name and phone, then POST `/contacts/{contactId}/attributes` to set source=crm-import.

### Inbound Event Streaming

Operators configure webhooks via POST /webhooks to push every inbound message, delivery receipt, and chat status change into their own infrastructure in real time. This avoids polling /chats and enables low-latency follow-ups such as routing a high-intent message to a human agent within seconds.

Example prompt: Call POST /webhooks with target_url=https://example.com/heyy and events=[message_in,delivered,read], then verify the webhook is active via GET /webhooks.

### AI Agent Conversational Operations

Through Jentic, an AI agent can search 'send a WhatsApp message' and receive Heyy's send schema, including the channelId path parameter. Jentic's vault holds the JWT, so the agent can drive multi-channel conversations - send, monitor delivery, trigger follow-up automations - without seeing the credential.

Example prompt: Search Jentic for 'send a whatsapp message', load the schema for POST /{channelId}/whatsapp_messages/send, and execute with channelId=WA-001 and contact phone.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/contacts` | Create a contact |
| POST | `/{channelId}/whatsapp_messages/send` | Send a WhatsApp message on a channel |
| POST | `/{channelId}/broadcasts` | Create a broadcast on a channel |
| POST | `/{channelId}/broadcasts/{broadcastId}/recipients` | Add recipients to a broadcast |
| POST | `/{channelId}/broadcasts/{broadcastId}/start` | Start a broadcast |
| POST | `/webhooks` | Create a webhook subscription for inbound events |
| POST | `/automations/{automationId}/trigger` | Trigger a configured automation |

## Key resources

- **Contacts** — Create, update, delete contacts and manage their custom attributes
- **Broadcasts** — Create, schedule, start, and audit broadcast campaigns per channel
- **Channels** — List connected omnichannel sources (WhatsApp, web chat) and their templates
- **Webhooks** — Configure subscriptions for inbound and delivery events
- **Automations** — Trigger named multi-step automations against a contact
- **Chats** — List and update active chat threads in the Heyy inbox
- **Labels and Attributes** — Manage shared labels and custom attributes for contacts

## Why Jentic

- **Setup:** Wiring the Heyy API by hand means learning its bearer JWT auth and threading the channelId through the URL on messaging, broadcast, and automation calls. Through Jentic you install once, import the Heyy API from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Heyy puts the channel and broadcast id in the URL path (/{channelId}/broadcasts/{broadcastId}/...), so a rule can pin your agent to one channel. You choose the operations it may call, so starting a broadcast or triggering an automation is only included if you add it, while creating contacts and adding recipients stays separate.
- **Credential handling:** Your Heyy bearer JWT is stored once, encrypted, by your own Jentic One instance and injected as the Authorization header at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'send a WhatsApp message' or 'create a broadcast', and Jentic returns the matching Heyy operation with its input schema including the channelId path parameter, so the agent calls the right endpoint without scanning the spec.

## Related APIs

- **Twilio API** — Twilio offers SMS, voice, and WhatsApp messaging at the carrier layer with broader programmable telephony
- **Sendbird API** — Sendbird provides in-app chat and messaging SDKs with similar contact and channel models
- **Chatwoot API** — Chatwoot is an open-source customer messaging platform with similar agent inbox features

## FAQ

### What authentication does the Heyy API use?

Heyy uses Bearer JWT authentication. Generate the token from the Heyy console and pass it in the Authorization: Bearer <token> header. Through Jentic, the JWT is stored in the encrypted vault and injected at execution time.

### Can I send a WhatsApp message via the Heyy API?

Yes. POST /{channelId}/whatsapp_messages/send accepts the contact phone, message body, and optional template references for the named WhatsApp channel. Replace {channelId} with the connected channel id you can read from GET /channels.

### How do I run a broadcast campaign through Jentic?

Run pip install jentic, search for 'create a whatsapp broadcast', and chain three calls: POST /{channelId}/broadcasts to create, POST /{channelId}/broadcasts/{broadcastId}/recipients to attach contacts, then POST /{channelId}/broadcasts/{broadcastId}/start to begin delivery. Jentic resolves the JWT and channelId per call.

### What are the rate limits for the Heyy API?

Rate limits are set per Heyy plan and channel - WhatsApp itself imposes per-template and per-second messaging limits enforced by Meta. The API returns HTTP 429 when exceeded; back off and pace broadcasts using the recipients endpoint to stay under the channel quota.

### How do I get notified when a contact replies?

Configure a webhook via POST /webhooks with target_url and an events list including message_in. Heyy will push inbound message events to that URL, removing the need to poll /chats.

### Can I trigger an automation against a specific contact?

Yes. POST `/automations/{automationId}/trigger` fires a configured automation flow for a contact, useful for ad-hoc onboarding kicks or escalation paths from another system.

### Can I limit what my agent is allowed to do with the Heyy API?

Yes. Because you run Jentic One yourself, your own rules decide which Heyy operations and credentials the agent may use, so you can approve reading contacts and channels while withholding higher-impact calls. Since Heyy puts the channel and broadcast id in the URL path, such as /{channelId}/broadcasts/{broadcastId}/start, a rule can pin the agent to a single channel. You choose each operation it may call, so starting a broadcast or firing POST `/automations/{automationId}/trigger` is included only if you add it, while creating contacts and adding recipients stay separate.