Connected actions: give the Secretary live data
Register an endpoint the Secretary calls while it chats, to look something up or to make a change the customer confirms, define its parameters, answer the call, and get it approved and switched on.
A connected action is an https endpoint on your system that a business's Secretary can call in the middle of a conversation: to look something up, or, once the customer has confirmed it, to make a change. When a customer asks for something your lookup returns, the Secretary calls it, reads your answer, and replies from it.
- RegisterPOST /api/v1/actions.
- Build the endpointVerify, look up, answer JSON.
- Owner testsWith real values, in the dashboard.
- Owner switches it onLive on every channel.
When to use one
Use an action for data that is too large to copy, changes often, or should not leave your system in bulk: stock, prices, where a delivery is, availability in another system, order status in your own store. For text that changes rarely, such as product details and answers to common questions, push knowledge instead.
An action either looks something up (effect: "read", the default) or makes a change (effect: "write"): opens a support ticket, books a callback, saves a request in your system. What a lookup returns only becomes information the Secretary reads. A write runs only after the customer says yes to exactly what will be sent; see Write actions below.
The examples on this page come from different kinds of businesses: a parts supplier that checks stock (check_stock), and a courier that tracks parcels (track_shipment) and opens support tickets (create_support_ticket).
How a conversation uses a lookup
- A customer writes: "Do you have 200 M8 hex bolts at the Harbour Road branch?"
- Before replying, the Secretary sees your actions' names, descriptions and parameters, and decides whether this message needs one.
- It calls yours with
{ "item": "M8 hex bolt", "location": "Harbour Road", "quantity": 200 }. Only values the customer actually gave are used; if a required one is missing, it asks the customer first. - Your endpoint answers with JSON.
- The Secretary replies from your data: it quotes figures exactly, mentions a sample size, date or source when you include one, describes only what your data covers, and shares a link only when your data has one.
- If your endpoint fails, it tells the customer it could not check just now. It never fills the gap with a guess.
At most 2 lookups are made for one customer message, and at most 6 in one phone call. On a phone call the Secretary reads your figures out loud, so plain numbers with a unit and currency work best; conversation.channel is voice.
Registering an action
POST /api/v1/actions
Authorization: Bearer ord_live_...
Content-Type: application/json
{
"name": "check_stock",
"title": "Stock check",
"description": "Live stock for a part at one of our branches, by part name or part number. Returns the quantity in stock, the unit price in USD, the expected restock date when it is out of stock, and a link to the product page. Our own branches only, not resellers.",
"url": "https://api.example.com/ordina/check-stock",
"parameters": {
"type": "object",
"properties": {
"item": { "type": "string", "description": "Part name or part number, for example M8 hex bolt or HB-M8-40" },
"location": { "type": "string", "description": "Branch", "enum": ["Northside", "Harbour Road", "Airport"] },
"quantity": { "type": "integer", "description": "How many the customer needs" }
},
"required": ["item"]
}
}
The response is 201 with the action and its secret. Store the secret now; it is never shown again.
| Field | Rules |
|---|---|
| name | 3 to 40 characters: lower-case letters, digits, underscores, starting with a letter. Unique within the business. |
| title | Required, up to 60 characters (a longer one is cut). What the owner sees in their dashboard, and, for a write action, the start of what the customer is asked to confirm. |
| description | 20 to 600 characters. What the Secretary reads to decide when to call it. |
| url | A public https address. No credentials in it, no internal addresses, no redirects. |
| parameters | Optional. See below. |
| effect | Optional. "read" (the default) or "write". See Write actions below. |
| customer_fields | Optional, for a write action only: which of the customer's contact details it receives, any of "name", "email", "phone", each once. Default []. A read action never receives them. |
| customer_proof | Optional, for a write action only: "verified" (the default) or "stated". See Write actions below. |
A business can have up to 10 actions, counting every key's and app's. Past that, a new one is refused with 400.
Parameters
A small, flat subset of JSON Schema: an object whose properties are each one of
| type | Notes |
|---|---|
| string | Up to 200 characters arrive. Add enum (1 to 50 values, each up to 80 characters) to allow only those. |
| number | Commas and spaces are removed, so "1,200" arrives as 1200. |
| integer | A whole number. 2.5 is refused. |
| boolean | true or false. |
Every property needs a description (up to 200 characters are kept). Property names are lower case letters, digits and underscores, starting with a letter, up to 40 characters. Up to 8 properties. Nested objects and arrays are not supported, because the Secretary fills parameters from a conversation and a flat form is what it fills reliably.
A property may not ask for the customer's contact details: a name containing email, phone, mobile, WhatsApp, SMS, address, street, postcode, a first, last, full or customer name, or a bare name, is refused with 400 and field set to the property. This holds for every action. A lookup is about what the customer asked, never who they are: name the property for what it looks up instead, such as item, tracking_number or product_name. A write action that needs the customer's email, phone or name declares it in customer_fields instead, and Ordina fills it from what it knows, never the Secretary.
Before anything reaches you, Ordina checks the Secretary's values against your schema: unknown properties are dropped, an enum value is matched without regard to case and sent exactly as you wrote it, and a call with a missing required value or a wrong type is never sent.
Writing a good description
The description is the only thing the Secretary has to decide when to call you. Say:
- What it returns, with the units and currency: "the quantity in stock, the unit price in USD".
- What it needs: "by part name or part number, at one of our branches".
- What it does not cover, if customers might assume it does: "our own branches only, not resellers".
Avoid instructions such as "always call this" or "tell the customer to sign up". They are ignored at best, and they make a reviewer less likely to switch your action on.
What your endpoint receives
POST https://api.example.com/ordina/check-stock
Content-Type: application/json
Accept: application/json
User-Agent: Ordina-Actions/1.0 (+https://www.useordina.com)
X-Ordina-Action: check_stock
X-Ordina-Call: call_k2D8...
X-Ordina-Signature: t=1790848800,v1=9a41...
{
"id": "call_k2D8...",
"action": "check_stock",
"arguments": { "item": "M8 hex bolt", "location": "Harbour Road", "quantity": 200 },
"business": { "id": "2b7d...", "handle": "harbourparts" },
"conversation": { "id": "c0a9...", "channel": "web" },
"test": false,
"created_at": "2026-10-01T10:00:00.000Z"
}
| Field | Notes |
|---|---|
| id | Unique per call. Matches X-Ordina-Call. |
| arguments | Only your declared properties, already type-checked. Required ones are always present. |
| business | Which business's Secretary is asking. One action belongs to one business. |
| conversation | The conversation id and channel (web, whatsapp, telegram, instagram, messenger, email, voice). Null for a test. |
| test | True when the owner pressed Test in the dashboard. A test must change nothing. |
Verify X-Ordina-Signature with the action's secret: see Verify signatures. A lookup never receives the customer's name, email or phone, and an action whose parameters ask for one is refused when you register it. A write action receives only the contact fields it declared in customer_fields and the owner approved, in a separate customer block.
What your endpoint returns
- Status 2xx, a JSON body, within 5 seconds, at most 16 KB.
- Any JSON shape works. Include what a careful answer needs: the figures, their unit and currency, the date, a link.
{
"item": "M8 hex bolt, zinc plated, 40 mm",
"part_number": "HB-M8-40",
"location": "Harbour Road",
"in_stock": 1450,
"enough_for_quantity": true,
"unit_price": 0.12,
"currency": "USD",
"restock_date": null,
"checked_at": "2026-10-01T10:00:00Z",
"url": "https://example.com/parts/hb-m8-40"
}
- Nothing found is still a 200, said plainly:
{ "found": false, "reason": "No part matches HB-M8-99" }. The Secretary then says so instead of guessing. - Keep it small. Only the first 4,000 characters of your compact JSON reach the Secretary; anything after that is cut.
These count as a failure, and the Secretary tells the customer it could not check: a non-2xx status, a redirect, a body that is not JSON, a body over 16 KB, or no answer within 5 seconds.
Write actions
A write action changes something in your system, or sends something, for the customer: opens a support ticket, books a callback, saves a request. It runs only after the customer says yes to exactly what will be sent, and only once the owner has switched it on.
This one, for a courier, opens a ticket in its help desk:
{
"name": "create_support_ticket",
"title": "Support ticket",
"description": "Opens a support ticket in our help desk about a parcel that is late, damaged or missing. Use it when the customer asks us to look into a delivery. Our team replies by email within one working day.",
"url": "https://api.example.com/ordina/support-tickets",
"parameters": {
"type": "object",
"properties": {
"tracking_number": { "type": "string", "description": "The parcel's tracking number, for example SC123456789" },
"problem": { "type": "string", "description": "What went wrong", "enum": ["Late", "Damaged", "Missing"] },
"summary": { "type": "string", "description": "The problem in the customer's own words, in one or two sentences" }
},
"required": ["tracking_number", "problem"]
},
"effect": "write",
"customer_fields": ["email"],
"customer_proof": "stated"
}
customer_fields lists the contact details the action receives: any of "name", "email" and "phone". Ask only for what the action needs. They are never parameters: Ordina fills them from what it knows about the customer, never from what the Secretary writes, and sends them in a separate customer block.
customer_proof says how sure Ordina must be of an email or phone before it sends one:
"verified"(the default): only an email or phone the channel proved. A phone number is proved when the customer writes from it on WhatsApp, which needs the business's own WhatsApp number. An email address is proved when the customer emails the business from it and the message passes the sender checks (SPF or DKIM), which is weaker proof than a phone. An address or number the customer types is not proof. When the channel cannot prove it, the Secretary tells the customer this can be done on a channel that can, or, when the business has no such channel, that the team can help them directly. Use it when the contact detail decides who gets something, such as a CRM'srequest_callbackwith"customer_fields": ["name", "phone"], which calls back the number the customer writes from on WhatsApp."stated": what the customer typed is enough. Use it for "send it to me" actions, such as a ticket whose replies go to the email address the customer gives.
A name is always as the customer gave it, and never proves who they are.
How a conversation uses a write action
- A customer writes: "My parcel SC123456789 arrived damaged, the box was crushed and the lamp inside is broken. Can you look into it?"
- The Secretary fills the parameters, checked against your schema like any call, and Ordina gathers the contact fields you declared. If one is missing, the Secretary asks for it (
stated), or says it can be done on a channel that proves it (verified). - Ordina shows the customer what will be sent, built from your title, the details and the contact fields (never written by the AI), and asks for a yes. Here, once the Secretary has asked for the customer's email address: "Support ticket (tracking number: SC123456789, problem: Damaged, summary: The box was crushed and the lamp inside is broken). Sent to tunde@example.com." On the website chat the customer also gets Confirm and Cancel buttons.
- Only the customer's next message can confirm it, and only a clear yes. A clear no cancels it, and so does a message about something else, or a reply more than 30 minutes later.
- A yes that comes within 1.5 seconds of the request being shown, typed or tapped, neither confirms nor cancels it: nobody can read the details that fast. The request stays waiting, the customer is asked to check the details and reply yes, and their next message is the one that counts.
- Ordina checks the action is still switched on and unchanged since it asked, then makes one signed call to your endpoint, and tells the customer what happened, from your answer.
What a write call receives
The same headers as a lookup, plus Idempotency-Key:
POST https://api.example.com/ordina/support-tickets
Content-Type: application/json
Accept: application/json
User-Agent: Ordina-Actions/1.0 (+https://www.useordina.com)
X-Ordina-Action: create_support_ticket
X-Ordina-Call: call_Q7m1...
X-Ordina-Signature: t=1792058404,v1=4c2e...
Idempotency-Key: 3f0c2a8e-5b1d-4b8e-9a7c-2d4e6f8a1b3c
{
"id": "call_Q7m1...",
"action": "create_support_ticket",
"arguments": { "tracking_number": "SC123456789", "problem": "Damaged", "summary": "The box was crushed and the lamp inside is broken" },
"business": { "id": "9e4a...", "handle": "swiftcourier" },
"conversation": { "id": "5e55c0f2-...", "channel": "whatsapp" },
"test": false,
"created_at": "2026-10-15T10:00:04.350Z",
"effect": "write",
"idempotency_key": "3f0c2a8e-5b1d-4b8e-9a7c-2d4e6f8a1b3c",
"confirmed_at": "2026-10-15T10:00:04.120Z",
"customer": {
"email": { "value": "tunde@example.com", "proof": "stated" }
}
}
| Field | Notes |
|---|---|
| effect | Always "write" on a write call. |
| idempotency_key | The same value as the Idempotency-Key header, and as proposal_id in the action events: the identity of this one confirmed request. |
| confirmed_at | When the customer said yes: the same time as confirmed_at in the action.confirmed event. |
| created_at | When Ordina made this call, a moment after the yes. |
| customer | Only the fields in your customer_fields that the owner approved, each as { "value", "proof" }. proof is "verified" (the channel proved it) or "stated" (as the customer typed it); a name is always "stated". |
What a write call returns
- Status 2xx and
{ "ok": true }, within 10 seconds, when the change was made. Add amessage(up to 300 characters) to tell the customer something more:{ "ok": true, "message": "Your ticket number is T-48213. We reply by email within one working day." }. { "ok": false, "error": "..." }when it could not be made. The customer is told it did not go through and nothing was changed, so change nothing when you answer this way.erroris for the call history, not the customer.- A non-2xx status counts the same as
{ "ok": false }. So does a call Ordina could not deliver at all (the connection was refused, the address did not resolve, or the certificate was not valid): nothing reached you. - No answer within 10 seconds, or a dropped connection, is recorded as unknown: Ordina could not learn whether the change was made. So is a 2xx that does not say
"ok": trueor"ok": false: a body that is not JSON, JSON withoutok, or a body over 16 KB. The customer is told it could not be confirmed and that the team will check, and the owner is asked to check with you.
What the customer reads is Ordina's own sentence, never the AI's: "Done:" and what was confirmed, plus your message as plain text.
Idempotency and retries
- Treat the Idempotency-Key as the request's identity. When the same key arrives twice, change nothing the second time and answer the same way you did the first time.
- Ordina does not retry a write by itself. The same key is only ever sent again for the same request the customer confirmed, never for a different one.
- Each confirmation has its own key: a customer who asks for two tickets confirms twice, and you get two keys.
Test calls
The owner's Test (no change is made) button sends a real, signed call to your write action with test: true. It has the body of a lookup call: no effect, idempotency_key, confirmed_at or customer, and no Idempotency-Key header. Treat it as a dry run: check the request, answer as you would, and change nothing.
Where write actions run
On every chat channel: the chat page, the website widget, WhatsApp (on the business's own number), Telegram, Instagram, Messenger and email. Not on phone calls yet: on a call the Secretary only uses lookups.
Approval: switching it on
Every action arrives switched off. The business owner:
- Opens Integration, then Connected actions.
- Reads your title and description, and presses Test with real values. They see exactly what the Secretary would read.
- Presses Switch on.
For a write action, the owner is asked once more before it is switched on, with your app's name, what it says it does, where the request goes, and the contact details it receives.
Only the owner can switch an action on or off; the API cannot. Any change you make through PATCH /actions/{id}, to the title, the description, the parameters, the url, the effect, the customer_fields or the customer_proof, switches the action off until the owner approves it again. The dashboard shows them what changed since they approved it, field by field, next to the Switch on button. Tell the owner when you change an action, so it is not off for long.
Revoking your key, or the owner disconnecting your app, also switches your actions off.
Watching it work
GET /api/v1/actions/{id}returns the 10 most recent calls: arguments, status (ok, error, timeout, rejected, unknown), HTTP status, time taken, any error, and the start of your response. A write call also has itsidempotencyKey, andcustomerFieldsSent: which contact fields went out, never their values.- The owner sees the same history in the dashboard, with a warning after 3 failures in a row.
rejectedmeans Ordina did not send the call: the Secretary's values did not fit your schema, or, for a write, it could no longer run as confirmed, for example because the action changed or was switched off before the customer's yes. It does not count against your endpoint.unknownmeans a write got no answer in time, or the connection dropped. Look up its Idempotency-Key in your own logs.
Checklist before you hand it to the owner
- The endpoint verifies the signature and rejects old timestamps.
- It answers in well under 5 seconds, including a cold start.
- "Nothing found" is a 200 with a reason, not a 404.
- The response carries units, currency and a date where they matter.
test: truecalls work, change nothing, and do not count as real usage in your analytics.- The description says what it returns and what it needs, in plain words.
- A write action answers
{ "ok": true }only when the change was made, within 10 seconds. - A write action treats the Idempotency-Key as the request's identity: the same key twice changes nothing the second time.
- A write action asks for no more contact details than it needs.
