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-tokenis 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.
callTokenalso takes the token itself, if the page already has one.- With no
environmentIdorversionRef, the call runs what prod serves.
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 passcallerKey: an ID for the person that stays the same across visits, such as your own user ID (1 to 200 characters, never a secret).
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: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:
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 intools with voiceEnablement: true. See Web tools.
Related
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.