canonical: https://jentic.com/apis/orsay.ai/orsay

# Orsay AI API

Jentic publishes the only available OpenAPI specification for Orsay AI API, keeping it validated and agent-ready. Orsay AI is a conversational-commerce platform that lets brands run AI agents over Instagram and WhatsApp to qualify leads, hold sales conversations, and execute follow-up sequences. The 33 endpoints span agent management, conversation history, lead context, integrations with Instagram and WhatsApp accounts, message-level feedback, sequence orchestration, organization configuration, and billing. It targets sales and customer-acquisition teams that want to automate first-touch outreach while keeping humans in the loop for handover.

## For AI agents

Run AI sales agents over Instagram and WhatsApp, manage conversations and leads, and orchestrate follow-up sequences through the Orsay AI platform.

## Scope

Does not handle payment processing, ad campaign management, or SMS/email channels - use for AI-driven Instagram and WhatsApp conversations only.

## Capabilities

- List and inspect AI agent configurations through GET `/v1/agents` and GET `/v1/agents/{agent_id}`
- Send messages from a configured agent into a conversation via POST `/v1/agents/{agent_id}/message`
- Retrieve full conversation history and search across conversations using GET `/v1/conversations` and GET `/v1/conversations/search-index`
- Connect Instagram and WhatsApp accounts through POST `/v1/integrations/instagram/account` and POST `/v1/integrations/whatsapp/account`
- Look up the lead behind a conversation with GET `/v1/lead/{lead_id}` for CRM enrichment
- Submit message-level feedback for fine-tuning via POST `/v1/conversation/{lead_id}/messages/{message_id}/feedback`
- Build and run automated outreach sequences through `/v1/sequences` endpoints

## Use cases

### Instagram DM Lead Qualification

Brands receiving high inbound DM volume on Instagram can configure an Orsay agent to qualify leads in chat, ask discovery questions, and route hot prospects to a human. The integrations endpoints connect the Instagram account, and the agent endpoints drive the actual conversation through POST `/v1/agents/{agent_id}/message.`

Example prompt: POST `/v1/integrations/instagram/account` to connect, then POST `/v1/agents/{agent_id}/message` to reply to inbound DMs with qualification questions.

### WhatsApp Outbound Sequences

Teams running paid acquisition into WhatsApp can use Orsay's sequence endpoints to deliver multi-step nurture flows that branch on response. POST `/v1/sequences` creates the sequence definition and POST `/v1/agents/{agent_id}/message` handles per-step delivery, with handoff to humans on conversion signals.

Example prompt: POST `/v1/sequences` with a 3-step welcome flow, then enroll new leads via the sequence enrollment endpoint and let the agent run delivery.

### Human Handoff on Buy Intent

When a conversation shows buy intent, the agent should step back. PATCH `/v1/conversation/{lead_id}/ai` disables the AI on that thread so a human seller takes over without losing chat context, and GET `/v1/lead/{lead_id}` surfaces the full lead profile for the human's first reply.

Example prompt: PATCH `/v1/conversation/{lead_id}/ai` with enabled=false when intent score crosses threshold, then GET `/v1/lead/{lead_id}` for the human seller's briefing.

### Conversation Export for Analytics

Operations teams want full conversation data in their warehouse to compute per-agent close rate or train on real exchanges. POST `/v1/conversations/export` starts a job and the GET `/v1/conversations/export/{job_id}/download` endpoint returns the file for ETL.

Example prompt: POST `/v1/conversations/export`, poll GET `/v1/conversations/export/{job_id}/status`, then download via the /download endpoint.

### Agent-Driven Conversational Sales via Jentic

Sales-ops agents orchestrating multiple channels can drive Orsay through Jentic without learning all 33 endpoints. Jentic exposes the operations by intent and isolates the bearer token in the vault, letting another agent handle CRM updates while Orsay handles the chat.

Example prompt: Use Jentic to search 'send a message via my AI sales agent', load the POST `/v1/agents/{agent_id}/message` schema, and execute with the conversation id and message body.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/v1/conversations` | List conversations across the workspace |
| GET | `/v1/lead/{lead_id}` | Retrieve the lead behind a conversation |
| POST | `/v1/agents/{agent_id}/message` | Send a message via an AI agent |
| PATCH | `/v1/conversation/{lead_id}/ai` | Pause or resume the AI on a conversation |
| POST | `/v1/integrations/instagram/account` | Connect an Instagram account |
| POST | `/v1/integrations/whatsapp/account` | Connect a WhatsApp account |
| POST | `/v1/sequences` | Create a multi-step outreach sequence |
| POST | `/v1/conversations/export` | Start a conversation export job |

## Key resources

- **Agents** — Configure and run AI agents over messaging channels
- **Conversations** — Read, search, export, and update conversations
- **Leads** — Look up the lead profile behind a conversation
- **Integrations** — Connect Instagram and WhatsApp accounts
- **Sequences** — Define and manage multi-step outreach flows
- **Organizations** — Manage organization configuration and naming
- **Billing** — List products, subscriptions, and wallet balance

## Why Jentic

- **Setup:** Wiring the Orsay AI API by hand means setting up its bearer auth and mapping the conversation, lead, agent, and Instagram and WhatsApp integration routes yourself. Through Jentic you install once, import Orsay AI from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Orsay AI puts the agent id in the URL path (`/agents/{agent_id}/message`), so a rule can pin your agent to one Orsay agent for sending messages. You choose the operations it may call, so connecting an Instagram or WhatsApp account or exporting conversations is not included unless you add it.
- **Credential handling:** Your Orsay AI bearer token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'send a message in a conversation' or 'pause AI on a lead's conversation', and Jentic returns the matching Orsay AI operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Intercom API** — Intercom offers AI chat and messenger across web and mobile as an alternative to Orsay's Instagram/WhatsApp focus.
- **Instagram Graph API** — Instagram Graph is the underlying platform Orsay integrates with for DM-based agents.
- **OpenAI API** — OpenAI provides the underlying language models that often power conversational agents like Orsay's.

## FAQ

### Why is there no official OpenAPI spec for Orsay AI API?

Orsay AI publishes documentation on its docs site but not a maintained OpenAPI document. Jentic generates and maintains this spec so that AI agents and developers can call Orsay AI API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Orsay AI API use?

Orsay AI uses bearer-token authentication. Through Jentic the bearer token is stored encrypted in the vault and injected only at execution time, so the agent never sees the raw secret.

### Can I connect a WhatsApp account through the Orsay AI API?

Yes. POST `/v1/integrations/whatsapp/account` creates the integration, GET `/v1/integrations/whatsapp/account` lists existing connections, and GET `/v1/integrations/whatsapp/profiles` enumerates the linked WhatsApp profiles.

### What are the rate limits for the Orsay AI API?

The OpenAPI spec does not declare numeric rate limits. Messaging-channel rate limits (Instagram and WhatsApp) often dominate in practice - confirm Orsay's per-tenant limits with their team before scaling outbound volume.

### How do I pause the AI on a conversation through Jentic?

Search Jentic for 'pause AI on a conversation', load the PATCH `/v1/conversation/{lead_id}/ai` schema, and execute with enabled set to false. The agent stops responding while the human takes over.

### Does the Orsay AI API expose billing data?

Yes. GET `/v1/billing/products`, GET `/v1/billing/subscriptions`, and GET `/v1/billing/wallets` return the product catalogue, current subscription state, and wallet balance for the tenant.

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

Yes. Because you run Jentic One yourself, your own rules decide which Orsay AI operations and credentials the agent may use. Since Orsay puts the agent id in the URL path (POST `/v1/agents/{agent_id}/message`), you can pin your agent to a single Orsay agent for sending messages, and you choose exactly which operations it may call. That means higher-impact actions like connecting an Instagram or WhatsApp account or exporting conversations are excluded unless you explicitly allow them.