Attachments, surveys, and email verification

Add the interactive parts of a conversation to your own UI: file attachments, satisfaction surveys, and email verification. Each one is optional.

Attachments

Show an attach button only when file uploads are enabled for your chat, that is when state.config.features includes "file-upload".

Send files

Upload the files

Pass File or Blob objects, such as the files from an <input type="file">, or { name, type, data }:

const results = await chat.uploadFiles(files, {
  onProgress: ({ name, loaded, total }) => showProgress(name, loaded / total),
});

onProgress reports bytes as they’re sent in browsers and React Native. In other runtimes it fires only when each file completes.

Handle failed files

You get one result per file, so one failed file doesn’t fail the others:

const failed = results.filter((result) => !result.ok);
if (failed.length) showUploadErrors(failed.map((f) => `${f.name}: ${f.error}`));

Send the message

Pass the uploaded attachments with the message. The text can be empty:

const attachments = results.filter((result) => result.ok).map((result) => result.attachment);
if (text.trim() || attachments.length) {
  await chat.sendMessage({ text, attachments });
}

Show received files

Each message has an attachments array of { name, path, type, size }. Get a short-lived download URL when the visitor opens one:

const url = await chat.getAttachmentUrl(message, attachment);
window.open(url, "_blank");

Request the URL on demand rather than in advance, because it expires. Messages still sending have no URL yet.

Satisfaction surveys

When a message has kind: "csat_request", show a rating prompt. Load its text, then submit a rating from 1 to 5 and an optional comment:

const { csatMessage, lastRating } = await chat.csat.getConfig();
showRatingPrompt(csatMessage, lastRating);

await chat.csat.submit({ rating: 5, comment: "Quick and helpful" });

lastRating and lastComment hold a previous answer, so you can show it instead of asking again.

Email verification

When the AI Agent needs to confirm who the visitor is, it sends a message with kind: "email_verification_requested". Show a form that asks for an email, then for the code sent to it:

Send the code

await chat.verification.sendCode(email);

Check the code

const { success, reason } = await chat.verification.verifyCode(code);

If success is false, reason is invalid_code, max_attempts, or expired.

Confirm

A message with kind: "email_verification_verified" arrives, and the conversation continues.

To restore the form after a reload, call chat.verification.getStatus():

string

none, awaiting_email, awaiting_code, or verified. Show the email field for awaiting_email and the code field for awaiting_code.

string

The email the code was sent to.

number

How many more codes the visitor can try.

If your visitors are signed in, pass their email as a signed variable instead. Verified values skip this step.

Voice input

When state.config.features includes "transcription", you can offer speech-to-text. chat.getTranscriptionKey() returns a short-lived ElevenLabs key to use with the ElevenLabs speech-to-text client. If you use a CSP, allow wss://api.elevenlabs.io in connect-src.

Render messages and activity
API reference
Insights Hub: where satisfaction ratings show up

Migrate to Typewise

Channels

Integrations

Best practices

Attachments, surveys, and email verification

Attachments

Send files

Show received files

Satisfaction surveys

Email verification

Voice input

​Attachments

​Send files

​Show received files

​Satisfaction surveys

​Email verification

​Voice input

​Related

Attachments

Send files

Show received files

Satisfaction surveys

Email verification

Voice input

Related