Calling API

Search…
Calling API
If you'd like to create your own Cohere widget or programmatically start a call with your own logic, you can use our calling API!
An example custom calling widget
To start a call from your widget, use makeCall :
1
// Call this when the user clicks the "Talk now" button, for example.
2
Cohere.makeCall();
Copied!
To adapt the calling popup to your website layout, you can pass in an optional options object to makeCall.
Subscribing to call events
You can also subscribe to the call status to update the widget based on the current state:
1
const listener = (callStatus, attrs) => {
2
	// type CallStatus = 'closed' | 'dialing' | 'missed' | 'inCall' | 'ended'
3
	// type CallStatusAttrs = { pickupDuration?: number, callDuration?: number } | undefined
4
	// See table below for additional details
5
}
6
​
7
Cohere.addCallStatusListener(listener);
8
​
9
// You can also unregister a call status listener: 
10
Cohere.removeCallStatusListener(listener);
Copied!
Call Status
Description
Attributes
"closed"
The call window is not currently open
​
"dialing"
The call has been made but has not yet been picked up
​
"missed"
Nobody was able to pick up the call in time
​
"inCall"
The call has been accepted and is currently in progress
{ pickupDuration: number } – How long it took for an agent to pick up in milliseconds
"ended"
The call has ended after being picked up
{ callDuration: number } – How long the call lasted in milliseconds
Custom widget example
Here's an example React calling widget component that:
Has an expanded and collapsed state
Initiates calls and renders a widget based on the call status
Dispatches tracking events for when a call is made, picked up, or missed (the example API is for Mixpanel)
1
const CohereCallWidget = () => {
2
  // Tracks whether the widget is expanded/collapsed
3
  const [expanded, setExpanded] = useState(false);
4
​
5
  // Subscribe to the call status
6
  const [callStatus, setCallStatus] = useState("closed");
7
  useEffect(() => {
8
    Cohere.addCallStatusListener(setCallStatus);
9
    // Cleanup
10
    return () => Cohere.removeCallStatusListener(listener);
11
  }, []);
12
​
13
  
14
  if (callState === "closed") {
15
    return expanded ? (
16
      <button
17
        onClick={() => {
18
          Cohere.makeCall();
19
        }}
20
      >
21
        Talk to us
22
      </button>
23
    ) : (
24
      <button onClick={() => setExpanded(true)}>Need help?</button>
25
    );
26
  } else {
27
    return (
28
      <button onClick={() => Cohere.focusCallWindow()}>Return to call</button>
29
    );
30
  }
31
};
Copied!
API - Previous
Chime Widget
Call Layout Options
Last modified 27d ago
Copy link
Contents
Subscribing to call events
Custom widget example