Connect an AI Phone Agent to Your Own System

How it works.

One card is one request to your system, at one moment in the call. An agent can carry up to 12 cards, so each job gets its own.

When it runs	What it is for	How it connects to the agent	On the board
Before the call	Look the caller up by their number: their name, their account, an open booking.	What you save is written into the agent's instructions before it says hello.	Purple wire
During the call	Something the agent does when the conversation calls for it: check a booking, look up an order, log a job.	The card becomes one tool on the agent. It decides when to use it from your name and description.	Solid wire
After the call	Send what happened into your system: the summary, the transcript, what the caller gave.	The agent has no part in it, so it cannot forget. It runs off the finished call.	Dashed blue wire, blue card

The path of a during-the-call request: the caller asks, the agent picks the tool and fills in the fields it is responsible for, Talkify adds your token and the details it holds and calls your API, then hands the agent only the parts you allowed with a sentence saying what to do with them. Your token never leaves our servers.

Several things during a call means several cards. Checking a booking and logging a repair are two cards, and so two tools. You do not describe them both in one prompt: each card's description is what the agent uses to tell them apart, and we write the list of them into its instructions for you when you deploy.

What your API must do.

Most modern APIs already do all of this.

Requirement	Detail
Public https address	It must start with https:// and be reachable from the internet. Private networks, office-only addresses and our own servers are refused.
A token in a header	We send it in the header you name, exactly as you paste it, for example Authorization: Bearer abc123.
JSON back	The parts of the answer are read from JSON. Anything else counts as an answer with no details in it.
Answer quickly	Before the call: 2 seconds, because the caller is waiting for the hello. During the call: the time you set on the card, 5 to 30 seconds, 10 by default. Aim for under two seconds: that is silence on a phone call.
No redirects	A redirect is not followed. Give the final address.
Answer under 256 KB	Anything larger is refused rather than read. The agent is passed at most 2 KB of it, so return what a phone call needs.
Handle the rate	Each card sends at most 120 requests a minute.

How we read your status code

You answer	We treat it as	What the agent does
2xx	It worked, as long as your success test passes (see What comes back)	Your "when it works" sentence
404	Nothing found	Your "when nothing is found" sentence
401 403 other 4xx	Set up wrong. Not retried after the call, because it would fail the same way	Your "when it fails" sentence
429 5xx or no answer	Your system is having trouble. Tried up to 3 times after the call	Your "when it fails" sentence

After-the-call requests carry an Idempotency-Key header made of the call and the card, the same on every try. If your API honours it, a retry can never record one call twice. If it does not, match on the call reference field instead.

Every setting.

In the order they appear on the card, and what each one does to the agent.

Setting	What it does	Effect on the agent
Name	What the card is called on the board and in the call's activity.	Part of the tool's name and description, so make it say the job: "Check booking", not "API 1".
When it runs	Before, during or after the call. Moves the card to that lane and changes its colour.	Decides whether it reaches the agent as details, a tool, or not at all.
Description	One or two sentences, written to the agent.	The most important box on the card. During the call, it is how the agent decides to use this tool rather than another one.
Method	GET POST PUT PATCH DELETE, from your API's documentation.	None directly.
Address	The full https address. A word in curly brackets, like {booking_number}, is filled from a field of the same name, safely encoded.	Never shown to the agent.
Send the fields as	JSON or form fields, for POST, PUT and PATCH.	None.
Header it goes in, Token	Where your token goes and the token itself. Press Save token. Encrypted, write-only, shown only as its last four characters.	Never shown to the agent.
Other headers	Anything else your API wants, like a store id. These are not secret, so never put a key here.	Never shown to the agent.
Fields to send	The values in the request. See Fields to send.	The fields it is responsible for become what it must collect.
What comes back	Which parts of the answer may be used. See What comes back.	The only parts of your answer it ever receives.
When it works, nothing is found, it fails	A sentence for each. Left blank, a sensible default is used.	The matching sentence comes back with each answer as its instruction.
Then	After a failure: offer to take a message, put them through, or carry on.	Added to the failure instruction.
The caller waits for it	Ticked, the agent says it is checking first, and the caller hears typing. Untick for something quiet.	Stops silence on the line.
It changes something in your system	Tick for anything that writes. On by default for POST, PUT, PATCH and DELETE.	Reads the details back and gets a yes first, and the caller cannot talk over the send.
Before it sends	Your own wording for that read-back.	Replaces our default.
Seconds to wait	How long we wait for your API, 5 to 30 seconds.	Past this, it gets the failure sentence.

Fields to send.

One row for each value your API expects.

Column	What it does
Field name	The exact name your API expects: letters, numbers, underscores and hyphens, starting with a letter or underscore.
Sent	In the body, in the query, or in the address. Body fields need POST, PUT or PATCH.
Type	See below. It tells the agent the format, and we check it again before sending.
Where the value comes from	See below.
Describe it for the agent	What it is and how it should look: "The booking number, six digits". This is what the agent reads, so say the format.
The choices	For "one of a list": the only values allowed.
Example	Optional. Added to what the agent reads.
Must have it	During the call, the agent collects it first, and if it tries without it we send nothing and tell it what to ask for. After the call, the request is not sent without it, rather than sending a guess.

Types

Type	Sent as
Text	A string.
Number, whole number	A number. Whole numbers are rounded.
Yes or no	true or false.
Date, time	YYYY-MM-DD and 24 hour HH:MM.
Phone number	International format where we can tell, like +64211234567.
Email	Lower case. A value that is not an email address is left out.
One of a list	One of your choices, in your spelling.
Group of fields	A JSON object, with its own rows inside, up to 3 levels deep.
List	A JSON array of one type, or of groups.

Where a value can come from

Source	Before	During	After	What happens
The agent asks or works it out	No	Yes	Yes	During the call the agent gets it from the caller. After the call it is picked out of the transcript using your description, and left empty when it was not said.
Always the same value	Yes	Yes	Yes	A fixed value you type, like a source or a branch code.
A detail of the call	Yes	Yes	Yes	Filled by us, so the agent can never get it wrong or invent it. See the list below.
A value saved earlier in the call	No	Yes	Yes	Something another card on this agent saved. That is how a lookup passes a customer number to the next card.
What happened on the call	No	No	Yes	See the list below.

Call details

Caller's number
Number they rang
Call reference (not before the call: it does not exist yet)
Agent name
Business name
Date and time now
Today's date

What happened on the call

Call summary
Transcript as text
Transcript as a list of turns
How long the call took, in seconds
Whether the call went well
Details collected on the call

What comes back.

Your API can return everything it likes. The agent only ever gets what you list here.

Column	What it does
Where in the answer	The path to a value, with dots: booking.start. A list uses square brackets: items[].name reads the name from every item. After a test, the real paths are offered to pick from.
Call it	The name the agent sees it under. "Booking time" is better than bk_st_ts.
Who sees it	The agent can tell the caller: it may say it. For the agent only: it may act on it but is told never to read it out, like "behind on fees". Nobody, only saved: the agent never sees it at all. Use this for ids that only matter to your next card.
Save it for later	Keeps the value as a call variable, named api_ plus your name, for later cards and for the agent's instructions. Names must be unique across an agent's cards.
Only counts as found when	Many APIs answer 200 with {"found": false}. Name that path, and a false, empty or zero value counts as nothing found.

With nothing listed, the top level of your answer is passed on, cut short at 2 KB. That is fine for a first test. List the parts before you go live, because anything passed on is something the agent could read out.

What the agent receives.

Exactly what it is given, so nothing here is a mystery.

Your API answers

{
  "found": true,
  "booking": { "class": "Spin", "start": "6:00 pm", "room": "B" },
  "member": {
    "id": "M-778",
    "notes": "Behind on fees",
    "card": "4111"
  }
}

The agent is handed

{
  "ok": true,
  "found": true,
  "data": { "Class": "Spin", "Starts": "6:00 pm" },
  "for_you_only": { "Staff notes": "Behind on fees" },
  "message": "Tell them the class and the time."
}

The room and the card number were not listed, so they do not exist as far as the agent is concerned. The member id was set to "Nobody, only saved", so it is available to your next card and never to the agent.

Key	Meaning
ok	false when the request failed.
found	false when nothing was found or it failed. The agent is told it does not have that information and must not guess.
data	What it may tell the caller.
for_you_only	What it may act on and must never read out.
message	The instruction for this answer: your sentence for the outcome. When an answer worked but held no details, it is also told to state none.

Before the call

There is no conversation yet, so saved values are the only thing that reaches the agent, and a before-the-call card must save at least one. They are written into its instructions on their own lines, under the names you gave them. A blank means not found or not checked, and it is told never to guess or to mention the lookup. Your values can also go in your own wording on the agent card, as {{api_first_name}}. In the greeting, a caller with no match hears it without that part, so "Kia ora {{api_first_name}}, thanks for calling" becomes "Kia ora, thanks for calling". The card has to be on and finished, or the deploy stops and says so.

Before-the-call cards run on incoming calls only. On a call we place, the values start out blank.

After the call

Nothing is said, because the call is over. The request is sent once per call, in the background, and every try is on the call's activity.

Getting it right.

The checks that decide whether your agent handles every answer properly.

Write the description for the agent, not for yourself. Say when to use it and what it needs: "Use when the caller asks about an existing booking and gives a booking number." With several cards, make sure no two could describe the same request.
Say the format on every field the agent fills. "Six digits" and "as the caller said it" stop most bad requests.
List the parts of the answer. Only what the agent needs, under plain names. If a person on your front desk would not read it out, it is "for the agent only" or "nobody".
Set a success test when your API answers 200 for "not found". Otherwise an empty answer counts as found. The same trick handles a booking that has just been taken: answer {"booked": false}, make booked the success test, and write "That time has just gone, offer them another" as the "nothing found" sentence.
Have your API say the day, not just the date. Return "Thursday 5 November, 2:00 pm", not 2026-11-05T14:00. People confirm days by name, and it is how a caller catches a wrong one.
Booking through your API takes two cards. One checks availability, listing each time the agent may say and each slot id "for the agent only" in the same order. One makes the booking, with the slot id as a field the agent fills and "It changes something" ticked.
Write all three sentences. Say what to do, not what happened: "Check the number with them once, then offer to take a message." These are instructions, and the agent follows them.
Tick "It changes something" on anything that writes. The agent then reads the details back and gets a yes first.
Press Test for each outcome. Use a real record, a record that does not exist, and if you can, your API switched off. Each time, read "The agent would be told" and ask whether a new staff member could act on it.
Then ring it. Deploy and make a test call for each outcome. Ask for something the agent should not know, and check it does not say it. Check the card's outcome on the call's activity.

What is looked after for you

The agent never sees your token, your address or anything you did not list.
Call details are filled by us, so it cannot send the wrong caller's number.
With a date field, the agent also tells us the weekday it means. If the two disagree, nothing is sent to your system and it is told the right day, so a miscounted "this Thursday" never checks or books a Friday. Your system only ever receives the date.
A card that is not finished never goes live, and the builder says what is missing.
A value one card needs that no card saves stops the deploy, rather than failing on a call.
If your system is slow or down, the call carries on and the agent has words for it.

A worked example.

A gym, with three cards on one agent.

Card	Request	Fields	What comes back
Member lookup Before the call	GET /members	phone in the query, from the call detail "Caller's number"	first_name saved as first_name, may say. id saved as member_id, nobody.
Check booking During the call	GET /bookings/{booking_number}	booking_number in the address, the agent asks, must have. member in the query, saved value member_id.	booking.class and booking.start, may say. Success test found.
File the call After the call	POST /calls	summary and transcript, what happened on the call. member, saved value member_id. reference, the call detail "Call reference".	Nothing needed.

The requests we send for that call

GET /members?phone=%2B64211234567
Authorization: Bearer your-token

GET /bookings/123456?member=M-778
Authorization: Bearer your-token

POST /calls
Authorization: Bearer your-token
Idempotency-Key: conv_abc-handling-xyz
Content-Type: application/json

{
  "summary": "Caller asked about their Spin class.",
  "transcript": "Agent: Kia ora, Kauri Gym...",
  "member": "M-778",
  "reference": "conv_abc"
}

When it goes wrong.

Start with See recent calls on the card, under What happened on recent calls. For the last five calls it shows what each card sent, what came back and what the agent was told, in plain words, including a call that ended as soon as it was answered.

Start with Save and send a test on the card: it shows what was sent and what came back.

You see	Usually means
"Only https addresses can be called", "points at a private network"	The address must be public and https. A system on an office computer cannot be reached.
401 or 403	The token is wrong, expired, or in the wrong header. Paste a fresh one and press Save token.
404 on every test	The address is wrong, or a word in curly brackets has no field sending a value.
No answer	Your system took longer than the card waits. Raise the wait, or speed the endpoint up.
Agent says it found nothing when it should have	The success test names a path that is not in the answer. Check it against the test result.
Agent has nothing to say	The paths you listed are not in the answer. It is told to state no details rather than invent them.
Agent does not use the tool	The description does not match how callers ask. Say it in their words.
Agent uses the wrong card	Two descriptions overlap. Say when each one is for, and when it is not.
Before-the-call values are blank	Your system took longer than 2 seconds, or the caller's number did not match. Check your number format against the international format we send.
Nothing arrived after the call	Check the call's activity. A 4xx is the card set up wrong; a required field that was never said stops the send.

Changed something and nothing happened? A changed card does nothing until the build is deployed again. A new token is the one exception: it applies straight away. Still stuck? Get in touch through the help centre, with the call if you have one.

Common questions.

If the agent needs to do several things during a call, is each one a card?

Yes. One card is one request to your system, and each during-the-call card becomes its own tool the agent can use. Checking a booking and logging a job are two cards. The agent chooses between them from the name and the description you write on each, so say plainly when each one is for.

Does our token get shared with anyone?

No. Every request is made from Talkify's own servers, and the token is added at that moment. It is stored encrypted, it is never part of what the agent or the voice service is given, and nobody can read it back once it is saved.

What happens on a call if our system is down?

The call carries on. Before the call, the details are simply blank and the agent treats the caller as somebody new. During the call, the agent is told to say it cannot check right now and follows your fallback. After the call, the request is tried again.

Can the agent make up an answer our system did not give?

It is told not to in every answer. It only receives the parts of your answer you listed, a clear sentence on what to do with them, and an outright instruction to state nothing when no details came back. Test each case with the Test button and a test call before you rely on it.

Connect your own system.