Skip to main content
A call needs permission to start. The Web SDK gets it in one of two ways: with a public key in your page, or with a call token your server gets for each call.

Public key or call token?

Never put a secret key in a page. The SDK refuses one in a browser.

With a public key

start() gets a call token with the key and starts the call with it. The key can only start calls, in the one environment it was made for, so it’s safe to leave in the page. Use the staging key on your staging site and the prod key on your live site. A public key can’t choose a version or an environment: versionRef and environmentId are refused with it.

With a call token from your server

Your server asks Hamsa for a token with its secret key, and the page asks your server for one each time a call starts. A token starts one call and lasts about 30 seconds.
  • /hamsa/call-token is your own endpoint, not Hamsa’s. Protect it the way you protect the rest of your app, for example by letting only signed-in users call it.
  • Pass a function, as above, rather than a token you fetched earlier. The SDK calls it as the call starts, so the token is still fresh.
  • callToken also takes the token itself, if the page already has one.
  • With no environmentId or versionRef, the call runs what prod serves.
What your server can send when it asks for the token: The token decides the agent, version and environment, so the page doesn’t send versionRef or environmentId next to it. See Create a call token for the full API.

Pass values to the agent

params fill the agent’s variables. Each key is a variable name: letters, digits and underscores, not starting with a digit.

Keep a caller on one version during an A/B test

While an agent’s prod runs an A/B test, each call gets a version by weight. Phone callers stay on one side by their number. A web call has no number, so pass callerKey: an ID for the person that stays the same across visits, such as your own user ID (1 to 200 characters, never a secret).
Without it, each web call is assigned on its own. With call tokens, send callerKey to your server’s token request too.

Ask for the microphone first

Ask for the microphone before you start the call, so you can explain what to do if the visitor says no:
If you don’t, and the visitor refuses the microphone, the call still connects without their voice and error fires. End it with agent.end(). A chat never asks for the microphone.

If a call fails to start

If Hamsa refuses the call, error fires with a HamsaApiError. It has a message that says what to do, plus:
Other problems arrive the same way as a plain Error: the network, your callToken function failing or returning nothing, or a callerKey that isn’t 1 to 200 characters. With no error listener, start() rejects instead, so try { await agent.start(...) } catch (error) { ... } works too. Mistakes in your code throw straight away from new HamsaVoiceAgent(...): a secret key in a browser, a publicKey that doesn’t start with pk_, or a public key passed where an older API key goes.

Let the agent use your page

The agent can call functions in your page during the call, such as reading the cart or opening a product. Pass them in tools with voiceEnablement: true. See Web tools.

API keys

Create public and secret keys, and limit them to agents and domains.

During a call

End, pause, mute and more once the call has started.