Skip to content

Commit

Permalink
Updated Agent, Contact, and Connection API docs (#185)
Browse files Browse the repository at this point in the history
  • Loading branch information
@labelson
labelson authored Dec 9, 2019
1 parent 076e8a9 commit 99ca7d4
Showing 1 changed file with 204 additions and 12 deletions.
216 changes: 204 additions & 12 deletions Documentation.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -182,6 +182,12 @@ be called on behalf of the agent. There is only ever one agent per Streams
instantiation and all contacts and actions are assumed to be taken on behalf of
this one agent.

### `agent.onContactPending()`
```
agent.onContactPending((agent) { ... });
```
Subscribe a method to be called whenever a contact enters the pending state for this particular agent.

### `agent.onRefresh()`
```
agent.onRefresh(function(agent) { ... });
Expand Down Expand Up @@ -229,13 +235,19 @@ accept an incoming contact, or in other error cases. It means that the agent is
not routable, and may require that the agent switch to a routable state before
being able to be routed contacts again.

### `agent.onSoftphoneError()`
```
agent.onSoftphoneError(function(agent) { ... });
```
Subscribe a method to be called when the agent is put into an error state specific to softphone funcionality.

### `agent.onAfterCallWork()`
```
agent.onAfterCallWork(function(agent) { ... });
```
Subscribe a method to be called when the agent enters the "After Call Work" (ACW) state. This is a non-routable state which exists to allow agents some time to wrap up after handling a contact before they are routed additional contacts.

### `agent.getState()`
### `agent.getState()` / `agent.getStatus()`
```
var state = agent.getState()
```
Expand Down Expand Up @@ -305,6 +317,18 @@ Gets the agent's routing profile. The routing profile contains the following fi
* `queues`: The queues contained in the routing profile.
* `defaultOutboundQueue`: The default queue which should be associated with outbound contacts.

### `agent.getChannelConcurrency`
```
if (agent.getChannelConcurrency("VOICE")) { ... }
```
OR
```
const concurrencyMap = agent.getChannelConcurrency();
```
Gets either a boolean represented by a 1 or 0, or a map of channel type to 1 or 0. 1 represents an enabled channel. 0 represents a disabled channel.
* `channel`: A string ENUM representing the channel whose value to return.
The ENUM options are currently `"VOICE"` and `"CHAT"`

### `agent.getName()`
```
var name = agent.getName();
Expand All @@ -319,6 +343,12 @@ Gets the agent's phone number from the `AgentConfiguration` object for the agent
number that is dialed by Amazon Connect to connect calls to the agent for incoming and outgoing calls if
softphone is not enabled.

### `agent.getDialableCountries`
```
if (agent.getDialableCountries().includes(COUNTRY_CODE)){ ... }
```
Returns a list of eligible countries to be dialed / deskphone redirected.

### `agent.isSoftphoneEnabled()`
```
if (agent.isSoftphoneEnabled()) { ... }
Expand All @@ -339,7 +369,7 @@ Updates the agents configuration with the given `AgentConfiguration` object. Th

Optional success and failure callbacks can be provided to determine if the operation was successful.

### `agent.setState()`
### `agent.setState()` / `agent.setStatus()`
```
var routableState = agent.getAgentStates().filter(function(state) {
return state.type === AgentStateType.ROUTABLE;
Expand Down Expand Up @@ -367,6 +397,34 @@ Creates an outbound contact to the given endpoint. You can optionally provide a
You can optionally provide success and failure callbacks to determine whether the
operation succeeded.

### `agent.getAllQueueARNs`
```
const ARNs = agent.getAllQueueARNs;
```
Returns a list of the ARNs associated with this agent's routing profile's queues.

### `agent.getEndpoints` / `agent.getAddresses`
```
const endpoints = agent.getEndpoints(
queue_array,
{
succes: function_1,
failure: function_2
},
{
endpoints: [endpoint1, endpoint2, etc.]
maxResults: 95
);
```
Returns the endpoints associated with the queueARNs specified in `queueARNs`, along with any endpoints specified in `pageInfoIn.endpoints`.
* `queueARNs`: Required. Can be a signle QueueARN or a list of QueueARNs associated with the desired queues.
* `callbacks`: Optional. A structure containing success and failure handlers.
* `callbacks.success`: A function for handling a successful API call.
* `callbacks.failure`: A function for handling a failed API call.
* `pageInfoIn`: Optional. A structure containing options for the call to the LARS CTI API getEndpoints.
* `pageInfoIn.maxResults`: The maximum number of endpoints returned from this API.
* `pageInfoIn.endpoints`: A list of endpoints to add to the final list of endpoints returned by this API.

### `agent.toSnapshot()`
```
var snapshot = agent.toSnapshot();
Expand Down Expand Up @@ -415,6 +473,18 @@ contact.onIncoming(function(contact) { ... });
Subscribe a method to be invoked when the contact is incoming. In this state, the contact is waiting to be
accepted if it is a softphone call or is waiting for the agent to answer if it is not a softphone call.

### `contact.onPending()`
```
contact.onPending(function (contact) { ... });
```
Subscribe a method to be invoked when the contact is pending. Pending occurs after incoming and before connecting, when an agent has accepted or answered, but the backend has not yet acknowledged that a connection is being formed.

### `contact.onConnecting()`
```
contact.onConnecting(function (contact) { ... });
```
Subscribe a method to be invoked when the contact is connecting. This works with chat and softphone contacts. This state happens after the agent has accepted a softphone call or answered if not.

### `contact.onAccepted()`
```
contact.onAccepted(function(contact) { ... });
Expand All @@ -424,6 +494,12 @@ to an API call when it succeeds, and this is usually triggered by a UI interacti
accept button. The proper response to this API is to stop playing ringtones and remove any Accept UI buttons
or actions, and potentially show an "Accepting..." UI to the customer.

### `contact.onMissed()`
```
contact.onMissed(function(contact) { ... });
```
Subscribe a method to be invoked whenever the contact is missed. This is an event which is fired when a contact is put in state "missed" by the backend, which happens when the agent does not answer for a certain amount of time, or when the customer hangs up before the agent can answer.

### `contact.onEnded()`
```
contact.onEnded(function() { ... });
Expand All @@ -432,12 +508,24 @@ Subscribe a method to be invoked whenever the contact is ended or destroyed. Th
being ended by the agent, or due to the contact being missed. Call `contact.getState()` to determine the state
of the contact and take appropriate action.

### `contact.onACW()`
```
contact.onACW(function() { ... });
```
Subscribe a method to be invoked whenever the contact enters the ACW state. This is after the connection has been closed, but before the contact is destroyed.

### `contact.onConnected()`
```
contact.onConnected(function() { ... });
```
Subscribe a method to be invoked when the contact is connected.

### `contact.getEventName()`
```
logger.log(contact.getEventName(eventName));
```
Returns a string with `contactId::eventName` as the format.

### `contact.getContactId()`
```
var contactId = contact.getContactId();
Expand All @@ -459,19 +547,19 @@ var type = contact.getType();
```
Get the type of the contact. This indicates what type of media is carried over the connections of the contact.

### `contact.getState()`
### `contact.getStatus()`
```
var state = contact.getState();
var state = contact.getStatus();
```
Get a `ContactState` object representing the state of the contact. This object has the following fields:
Get a `ContactStatus` object representing the state of the contact. This object has the following fields:

* `type`: The contact state type, as per the `ContactStateType` enumeration.
* `duration`: A relative local state duration. To get the actual duration of the state relative
to the current time, use `contact.getStateDuration()`.

### `contact.getStateDuration()`
### `contact.getStatusDuration()`
```
var millis = contact.getStateDuration();
var millis = contact.getStatusDuration();
```
Get the duration of the contact state in milliseconds relative to local time. This takes into
account time skew between the JS client and the Amazon Connect backend servers.
Expand All @@ -485,6 +573,12 @@ Get the queue associated with the contact. This object has the following fields
* `queueARN`: The ARN of the queue to associate with the contact.
* `name`: The name of the queue.

### `contact.getQueueTimestamp`
```
var queueTimestamp = contact.getQueueTimestamp();
```
Get the timestamp associated with when the contact was placed in the queue.

### `contact.getConnections()`
```
var conns = contact.getConnections();
Expand Down Expand Up @@ -646,15 +740,15 @@ var connectionId = connection.getConnectionId();
```
Gets the unique connectionId for this connection.

### `connection.getEndpoint()`
### `connection.getEndpoint()` / `connection.getAddress()`
```
var endpoint = connection.getEndpoint();
```
Gets the endpoint to which this connection is connected.

### `connection.getState()`
### `connection.getStatus()`
```
var state = connection.getState();
var state = connection.getStatus();
```
Gets the `ConnectionState` object for this connection. This object has the
following fields:
Expand All @@ -663,9 +757,9 @@ following fields:
* `duration`: A relative local state duration. To get the actual duration of
the state relative to the current time, use `connection.getStateDuration()`.

### `connection.getStateDuration()`
### `connection.getStatusDuration()`
```
var millis = connection.getStateDuration();
var millis = connection.getStatusDuration();
```
Get the duration of the connection state, in milliseconds, relative to local time.
This takes into account time skew between the JS client and the Amazon Connect service.
Expand All @@ -676,6 +770,13 @@ var type = connection.getType()
```
Get the type of connection. This value is either "inbound", "outbound", or "monitoring".

### `connection.getMonitorInfo()`
```
var monitorInfo = conn.getMonitorInfo();
```
Get the currently monitored contact info, or null if that does not exist.
* `monitorInfo` = `{ agentName: string, customerName: string, joinTime: string }`

### `connection.isInitialConnection()`
```
if (conn.isInitialConnection()) { ... }
Expand Down Expand Up @@ -754,6 +855,97 @@ Resume this connection if it was on hold.

Optional success and failure callbacks can be provided to determine whether the operation was successful.

## VoiceConnection API
The VoiceConnection API provides action methods (no event subscriptions) which can be called to manipulate the state
of a particular voice connection within a contact. Like contacts, connections come and go. It is good practice not
to persist these object or keep them as internal state. If you need to, store the `contactId` and `connectionId`
of the connection and make sure that the contact and connection still exist by fetching them in order from
the `Agent` API object before calling methods on them.

### `voiceConnection.sendDigits()`
```
conn.sendDigits(digits, {
success: function() { ... },
failure: function() { ... }
});
```
Send a digit or string of digits through this connection.

### `voiceConnection.hold()`
```
conn.hold({
success: function() { ... },
failure: function() { ... }
});
```
Put this voice connection on hold.

### `voiceConnection.resume()`
```
conn.resume({
success: function() { ... },
failure: function() { ... }
});
```
Only has an effect if this connection was on hold when called.

### `voiceConnection.isOnHold()`
```
if (conn.isOnHold()) { ... }
```
Returns true if this connection is on hold, false otherwise.

### `voiceConnection.getMediaInfo()`
```
const mediaInfo = conn.getMediaInfo();
```
Returns the media info object associated with this connection.

### `voiceConnection.getMediaType()`
```
if (conn.getMediaType()==="SOFTPHONE") { ... }
```
Returns the softphone media type enum: `"SOFTPHONE"`.

### `voiceConnection.getMediaController`
```
const voiceController = conn.getMediaController();
```
Get the media controller associated with this connection.

## ChatConnection API
The ChatConnection API provides action methods (no event subscriptions) which can be called to manipulate the state
of a particular chat connection within a contact. Like contacts, connections come and go. It is good practice not
to persist these object or keep them as internal state. If you need to, store the `contactId` and `connectionId`
of the connection and make sure that the contact and connection still exist by fetching them in order from
the `Agent` API object before calling methods on them.

### `chatConnection.getMediaInfo()`
```
const mediaInfo = conn.getMediaInfo();
```
Get the media info object associated with this connection.

### `chatConnection.getConnectionToken()`
```
conn.getConnectionToken()
.then(response => {})
.catch(error => {});
```
Provides a promise which resolves with the API response from createTransport transportType chat_token for this connection through the createTransport LARS CTI API.

### `chatConnection.getMediaType()`
```
if (conn.getMediaType()==="CHAT") { ... }
```
Returns mediaType for a chat connection, which is `"CHAT"`.

### `chatConnection.getMediaController()`
```
const mediaController = conn.getMediaController();
```
Get the media controller associated with this connection.

## Utility Functions
### `Endpoint.byPhoneNumber()` (static function)
```
Expand Down

0 comments on commit 99ca7d4

Please sign in to comment.