Overview
Without Your API, the agent meets every user as a stranger. It asks questions your product already knows the answers to, and walks people through steps they've already done.
With Your API, Kulu reads what your own system knows about the person joining, such as their plan and how far their setup has got. The agent starts the call already knowing them.
What it gives you
- Shorter, more relevant calls. The agent moves past steps the user has already finished and spends the time on what's left.
- Fewer repeated questions. When your system already has an answer, the agent confirms it instead of asking from scratch.
- A personal experience. The agent can refer to the user's own account, plan and progress.
- The user stays in charge. If the user says something different from what your system shows, the agent goes by what the user says.
What your users experience
A user who has already connected their calendar clicks the Kulu button in your app. Instead of explaining how to connect a calendar, the agent says:
I can see your calendar is already connected, so let's move on to inviting your team.
What it takes
- Your engineering team provides an endpoint that returns what the agent should know about one user, for example their plan and setup progress. Many products already have something similar for their support chatbot.
- An admin adds that endpoint in the Kulu portal and tests it with a real user.
- Your app adds the user's ID and a sign-in token to the Kulu button, so Kulu knows who is joining.
Your data
Your system stays in control of who the user is, and the user's sign-in token is never stored. What your API returns isn't saved in our database: it's used during the call only. See Security and your data for the details.
Available on request:
Your API is switched on per organisation. Ask your Kulu contact to turn it on for you.
Integration guide
This part is for the engineers setting it up.
Before you start
You need:
- An HTTPS endpoint on a public host that answers a
GETrequest with what the agent should know about one user, as JSON or plain text. - A way for that endpoint to know who the user is: their user ID and a token your app issues for the signed-in user.
- Kulu's outbound IP addresses, if your API only accepts requests from allow-listed addresses. Ask your Kulu contact for them.
Set it up
Add your API
In the Kulu portal, open Integrations and choose Your API. Add an API with:
- Name, for example "Account context".
- What it returns: one line the AI reads, for example "Plan, billing and setup progress".
- Address: the
GETURL. You can put{user_id}or{email}in it, for examplehttps://api.example.com/users/{user_id}/onboarding.
Add the headers
Give each header a name and a type. Kulu fills in the value on every request:
| Type | You enter | Kulu sends |
|---|---|---|
| Secret | The value, once | The same value on every request |
| User ID | Nothing | The user's ID from the join link |
| Nothing | The user's email from the join link | |
| User's token | Nothing | The token your app issued for the user, exactly as it came in the join link |
| Kulu signature | A signing secret, once | A new token on every request that shows it comes from Kulu (HS256, iss and sub are kulu, valid for 5 minutes) |
Secrets are stored encrypted and never shown again. If you change the address, paste the secrets again.
Test with a real user
Enter a real user's ID, email and token, as your API needs them, and run the test. You'll see your API's answer. Save when it looks right.
Pass the user in the join link
In your agent's Deployment tab:
- Button Embed: add the
{{user_id}}and{{user_token}}tags. The generated code adds the user ID to the link, and the token at the end, after#user_token=. - Individual Link: fill in the User ID field.
The token goes after the #, a part of the link that browsers never send to a server. It must still be valid when the user clicks to join.
How it works in a call
- When the user joins, Kulu calls each API you've added once, all at the same time.
- The agent doesn't wait for the answers. It greets the user straight away and uses the data as soon as it arrives.
- On agents that guide users through steps, an AI step reads the answers and notes which steps the user has already done and what their answers are likely to be.
- Every agent in your organisation uses every API you've added.
Limits
GETrequests only, over HTTPS to a public host. Redirects aren't followed.- Up to 60 seconds and 512 KB per API.
- Kulu calls your APIs once, when the call starts, not during the call.
- If an API fails, takes too long, or has nothing to send because the link carries no user ID or token, the call goes ahead without it.
- Links sent with Email Batch don't carry a user's token yet, so calls started from an email run without data from an API that needs one.
Check it's working
In Analytics → Session history, the User context column shows how each call went: Loaded, Partly loaded, Failed or Skipped. Hover over it to see each API's result, such as a 401 or a timeout.
Security and your data
- Your API decides who the user is. Kulu passes the user's token to your API exactly as it came, and your API must check that it's valid and belongs to that user. Without a User's token header, anyone who can open your link could change the user ID in it, and the form warns you about this.
- The user's token goes only to your API. Kulu never stores or logs it, and removes it from the page address.
- Answers aren't stored in our database. They're kept in memory for up to 2 hours while the call runs. For each request, Kulu records only the outcome (status, timing and size), never the answer.
- The AI provider listed in our Data Processing Addendum processes the answers to match them to your agent's steps. What the agent says from them is part of the conversation, so it appears in the call's transcript.