> ## Documentation Index
> Fetch the complete documentation index at: https://docs.telzino.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Chat

> Text chat with an agent from your website

`TelzinoChat` lets a visitor chat with an agent by text. The agent answers with the same setup that answers its text messages: its prompt, tools and model. Chat uses the same [publishable key](https://docs.telzino.com/sdk/authentication.md#publishable-keys) as voice, so the page's origin must be on the key's allowed origins.

```bash theme={null}
npm install @telzino/voice
```

## Plain JavaScript

```ts theme={null}
import { TelzinoChat } from '@telzino/voice';

const chat = new TelzinoChat({
  publishableKey: 'pk_live_...',
  agentId: '3f1c2a4e-8b7d-4c3a-9e2f-1a2b3c4d5e6f',
});

chat.on('message', (m) => render(m));          // { id, role: 'user' | 'agent', text, timestamp }
chat.on('typing', (busy) => showTyping(busy)); // the agent is working on a reply
chat.on('error', (err) => console.warn(err.code, err.message));

await chat.load();                     // the earlier conversation, for a returning visitor
await chat.send('Do you open on Sunday?');
```

`send()` resolves once Telzino has accepted the message. The visitor's own message and the agent's reply both arrive as `message` events, in order. Call `chat.close()` when the chat widget goes away.

### Options

| Option | Default | |
| - | - | - |
| `publishableKey` | required | `pk_live_...` |
| `agentId` | required | The agent to chat with |
| `visitorId` | a random id kept in `localStorage` | Pass your own (8 to 64 letters, digits, `_` or `-`) to keep one conversation across devices, for example a hash of your user id |
| `apiBaseUrl` | `https://api.telzino.com` | |

### Returning visitors

The visitor id is stored in `localStorage` per agent, so a visitor who comes back continues the same conversation. `load()` fetches the latest 100 messages. If the browser blocks storage, each page load starts a new conversation.

## React

Inside [`<TelzinoProvider>`](https://docs.telzino.com/sdk/react), `useChat` gives you the thread and a `send` function.

```tsx theme={null}
import { useState } from 'react';
import { TelzinoProvider, useChat } from '@telzino/react';

function ChatBox({ agentId }: { agentId: string }) {
  const { messages, typing, error, send } = useChat(agentId);
  const [text, setText] = useState('');
  return (
    <form onSubmit={(e) => { e.preventDefault(); void send(text); setText(''); }}>
      {messages.map((m) => <p key={m.id} className={m.role}>{m.text}</p>)}
      {typing && <p className="typing">…</p>}
      {error && <p role="alert">{error.message}</p>}
      <input value={text} onChange={(e) => setText(e.target.value)} />
    </form>
  );
}

export default function App() {
  return (
    <TelzinoProvider config={{ publishableKey: 'pk_live_...' }}>
      <ChatBox agentId="3f1c2a4e-8b7d-4c3a-9e2f-1a2b3c4d5e6f" />
    </TelzinoProvider>
  );
}
```

`useChat(agentId, { visitorId })` accepts the same `visitorId` option. It needs a `publishableKey` on the provider; a provider configured only with a `session` function reports an `invalid_request` error.

## How replies arrive

After a message is sent, the SDK asks Telzino for new messages about once a second until the reply is in, for at most 90 seconds. After a failed request it waits longer each time, up to 15 seconds. Replies usually take 2 to 10 seconds, depending on the agent's model and tools.

## Errors

Errors are `TelzinoError`s with a `code`:

| Code | Meaning |
| - | - |
| `invalid_key`, `origin_not_allowed` | The key is wrong or this origin is not allowed on it |
| `embed_disabled`, `chat_disabled` | The SDK is off for the account, or chat is off for the agent |
| `agent_not_found` | No such agent for this key |
| `rate_limited` | Too many messages or polls; recoverable |
| `temporarily_unavailable`, `network` | Retry shortly |

See [Send Chat Message](https://docs.telzino.com/api-reference/chat/send.md) for the HTTP API and its limits.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.