Copy page

How-to

Deployed AI

The agents elsewhere in these guides answer your team. These two put an agent in front of people who have no account: a widget embedded on your site, and a voice agent with a real phone number.

Both wrap an agent you already have, so the knowledge, tools and prompt work you did for internal use carries straight over.

Chat widgets

Gated on module-chat-widget.

Code
curl -X POST https://api.genuineai.app/api/v1/chat-widgets \
  -H "X-Api-Key: gai_…" -H "X-Tenant-Id: <workspace-id>" \
  -H "Content-Type: application/json" \
  -d '{
    "widget_name": "Support",
    "widget_agent": "3f2a9c1e-…",
    "widget_origins": ["https://example.com"],
    "widget_welcome": "Ask us anything about ordering."
  }'

widget_origins is the allow-list of sites permitted to embed the widget. It is what stops someone else's page from running your agent on your credits, so keep it tight: a wildcard here lets anyone spend your budget.

Limits

widget_limits sets the guardrails on an anonymous surface:

maxMessagesPerSession	Caps one conversation.
maxSessionsPerIpPerDay	Caps one visitor.
maxInputChars	Caps one message.
sessionTtlMinutes	How long a session stays open.
dailyCreditCap	The one that matters. A ceiling on what this widget can spend per day.

Set dailyCreditCap before you go live. It contains a bad day to one widget rather than to your whole credit balance, because the public rate limits protect the platform rather than your budget.

Tools are off by default

Code
{ "widget_config": { "enableTools": true } }

Without this setting, the widget runs the agent with no tools and no connections, even if the agent carries them. The default is deliberate: an anonymous visitor should not be able to reach your connected systems by asking. Turn it on only when you have decided the public may reach whatever those tools touch.

Conversations and leads

GET /chat-widgets/{id}/sessions	Every conversation. leads_only=true narrows to those that captured contact details.
GET /widget-sessions/{id}	One lead with the conversation it came from.
GET /chat-widgets/{id}/analytics	Conversation and lead counts over the last days (30 by default).

The lead endpoint returns the contact and the transcript together, which is what a CRM handoff usually needs: not only who made contact, but what was said. Poll sessions with leads_only=true and a wses_created range for a lead feed without a webhook.

Voice agents

Gated on module-voice-agent. An agent, on a phone number, taking real calls.

Code
curl -X POST https://api.genuineai.app/api/v1/voice-agents \
  -H "X-Api-Key: gai_…" -H "X-Tenant-Id: <workspace-id>" \
  -H "Content-Type: application/json" \
  -d '{"vag_name": "Front desk", "vag_agent": "3f2a9c1e-…"}'

That creates the agent and its configuration. It has no phone number until you request one, which is a separate call because it is a separate commitment:

Code
curl -X POST https://api.genuineai.app/api/v1/voice-agents/<id>/phone-number \
  -H "X-Api-Key: gai_…" -H "X-Tenant-Id: <workspace-id>" \
  -H "Content-Type: application/json" \
  -d '{"country": "US", "areaCode": "305"}'

vag_limits bounds call volume and spend the same way widget_limits does, and vag_config.enableTools gates tools on exactly the same terms as the widget: off unless you turn it on.

Calls

GET /voice-agents/{id}/calls	The call log, filterable by vcall_status and vcall_created.
GET /voice-agents/{id}/calls/{callId}	One call in full.
GET /voice-agents/{id}/calls/{callId}/recording	The audio.
GET /voice-agents/{id}/analytics	Call count, total duration and credits consumed over the last days.

The recording endpoint streams audio rather than returning a provider URL. The provider's own links are raw bucket endpoints or expiring presigned URLs and are not reliably playable in a browser, so this endpoint resolves a working source per request. Expect audio rather than JSON, and do not cache the response as if it were a link.

Voice analytics report credits alongside duration, and both are worth watching: minutes are what the telephony provider bills, credits are what the model costs, and the two do not move together.

Choosing between the two

Widget	Visitors already on your site. Cheap to run, easy to cap, leads land as structured records.
Voice	People who would rather call. Carries a per-number cost whether or not anyone rings it.

Both are deployments of an agent rather than separate products, so improving the agent improves both. Point each at an agent whose knowledge you would be comfortable seeing quoted back to you by a stranger.

Next steps

• Agents and conversations covers the agent underneath both.
• Usage and credits is how you watch what public surfaces spend.
• External data describes what enableTools exposes.