Operations

This is the first operation the partner application invokes to notify Service Guide that the application is ready to handle CTI functionalities.

It should be invoked after initial setup of the partner application is complete, which includes:

• Setting up communication channels and websocket connections
• Initializing various SDKs, including the Service Guide SDK
• Completing all other initialization code

Service Guide expects this operation to be called when the partner application is loaded to confirm that it is ready to handle call center operations.

If Service Guide does not receive a response within a predetermined time, it reloads the partner application iFrame.

If the partner application can't be loaded after 3 attempts, Service Guide assumes the Partner Application is down and abandons attempts to load it. Service Guide notifies the agent about the failure to load the partner application.

This operation is used by the partner application to notify Service Guide of the agent's availability to take an incoming call.

The Service Guide displays one of these agent statuses, depending upon the payload when the operation is invoked:

• Ready
• Not Ready

When an agent is actively handling a call, the status is Not Ready.

Be aware that the partner application must invoke this operation to notify Service Guide when the agent should be moved to Not Ready status. Depending on the CTI vendor, this could be an explicit notification that the vendor sends to the partner application or it could be done by the partner application in response to when a call is connected.

{
    data: {
         isAgentReady: boolean
    },

    error: object<{
        isError: boolean, 
        message: string }> (optional)
   }
}

isAgentReady:

Whether the agent is currently ready to receive calls.

If the Partner Applications receives an error while updating the agent status, it notifies Service Guide about the error by including an "error" object in the payload instead of including a "data" object.

The error object has the following properties:

• isError: Boolean representing whether or not an error occurred.
• message: An error code representing the type of error that occured. Possible values:
  • "READY_​STATUS_​UPDATE_​FAILED"
  • "NOT_​READY_​STATUS_​UPDATE_​FAILED"

When an incoming call is received from the CTI vendor and sent to the partner application, invoke this operation to notify Service Guide about the incoming call.

{
    data: {
        phoneNumber: string,
        callId: string
   }
}

phoneNumber:

Incoming customer phone number.

callId:

A unique identifier representing the new incoming call session.

To be invoked when the new call session is established with the customer in response to an incoming call.

Note that the agent will not explicitly accept an incoming call, but must be automatically connected to the call using auto-answer capabilities. Depending upon the CTI vendor, this could be an explicit setting in the CTI backend, or the Partner Application might be required to invoke an explicit vendor API to accept the call when it is received.

Service Guide does not display Accept or Reject options for the agent.

In response to this operation, Service Guide will render the call controls that are needed for the agent to interact with the active call session.

{
    data: {
        phoneNumber: string,
        callId: string,
        connectedTime: integer | string | Date
    },

    error: object<{
        isError: boolean, 
        message: string }> (optional)
   }
}

phoneNumber: Customer phone number.

callId: A unique identifier representing the newly established call session.

connectedTime: An optional parameter representing the start of the conversation. If present, it can be an integer representing UNIX timestamp OR a String representing datetime in ISO-8601 OR a javascript Date object.

If the partner applications receives an error while establishing the call session with the customer and agent, it can notify Service Guide about the error by including the "error" object in the payload instead of including the "data" object.

Error object has following properties:

• isError: Boolean representing whether or not an error occurred.
• message: An error code representing the type of error that occurred. Possible values are "CONNECT_​FAILED".

Both the callReceived and initiatedCallSession operations expect a callId parameter. This is required because a CTI vendor might not generate a new call identifier until a call is connected. Therefore, the call identifier might not be available when the callReceived operation is invoked.

The "connectedTime" paramater can be used if the call was already in progress via another CTI software before the Service Guide window was opened. In this case, it is useful to send the timestamp from the beginning of the conversation so that Service Guide can correctly reflect the call length instead of starting the timer from 0.

The Partner Application can invoke this operation when the call is disconnected from the CTI vendor.

Note that if the agent disconnects the call in the Service Guide interface, this operation should be invoked when the call is actually disconnected by the CTI vendor in response to the Agent disconnect request.

{
    data: {
       callId: string,
       callDuration: number (optional)
    },

    error: object<{
        isError: boolean, 
        message: string }> (optional)
   }
}

callId:

A unique identifier for the call session that ended.

callDuration:

Optional call duration in seconds.

If the partner applications receives an error while disconnecting the call session, it can notify Service Guide about the error by including the "error" object in the payload instead of including the "data" object.

Error object has following properties:

• isError: Boolean representing whether or not an error occurred.
• message: An error code representing the type of error that occurred. Possible values are "DISCONNECT_​FAILED".

This operation should be invoked to notify Service Guide that a request to mute an ongoing call was successfully processed.

This operation can also be used to notify Service Guide if the call was externally muted so that Service Guide can update itself.

{
    data: {
       callId: string
    },

    error: object<{
        isError: boolean, 
        message: string }> (optional)
   }
}

callId:

A unique identifier for the call that was muted.

If the partner applications receives an error while muting the call, it can notify Service Guide about the error by including the "error" object in the payload instead of including the "data" object.

Error object has following properties:

• isError: Boolean representing whether or not an error occurred.
• message: An error code representing the type of error that occurred. Possible values are "MUTE_​FAILED".

This operation should be invoked to notify Service Guide that a request to un-mute an ongoing call was successfully processed.

It can also be used to notify Service Guide if the call was externally un-muted so that Service Guide can update itself.

{
    data: {
       callId: string
    },

    error: object<{
         isError: boolean,
         message: string }> (optional)
    }
}

callId:

A unique identifier for the call that was un-muted.

If the partner applications receives an error while unmuting the call, it can notify Service Guide about the error by including the "error" object in the payload instead of including the "data" object.

Error object has following properties:

• isError: Boolean representing whether or not an error occurred.
• message: An error code representing the type of error that occurred. Possible values are "UNMUTE_​FAILED".

This operation should be invoked to notify Service Guide that a request to put the call on hold was successfully processed.

It can also be used to notify Service Guide if the call was externally put on hold so that Service Guide can update itself.

{
    data: {
       callId: string
    },

    error: object<{
         isError: boolean,
         message: string }> (optional)
    }
}

callId:

A unique identifier for the call that is placed on hold.

If the partner applications receives an error while putting the call on hold, it can notify Service Guide about the error by including the "error" object in the payload instead of including the "data" object.

Error object has following properties:

• isError: Boolean representing whether or not an error occurred.
• message: An error code representing the type of error that occurred. Possible values are "HOLD_​FAILED".

This operation should be invoked to notify Service Guide that a request to resume a call that was previously put on hold was successfully processed.

It can also be used to notify Service Guide if the call was externally resumed so that Service Guide can update itself.

{
    data: {
       callId: string
    },

    error: object<{
         isError: boolean,
         message: string }> (optional)
    }
}

callId:

A unique identifier for the call that is resumed.

If the partner applications receives an error while resuming the call that was previously put on hold, it can notify Service Guide about the error by including the "error" object in the payload instead of including the "data" object.

Error object has following properties:

• isError: Boolean representing whether or not an error occurred.
• message: An error code representing the type of error that occurred. Possible values are "RESUME_​FAILED".

This operation should be invoked in response to the request transcript event to send the text transcript of the call. The partner application should request the transcript from the CTI backend via CTI-specific APIs.

It is not necessary to fetch the transcript from the CTI backend at the point when the call ends. If the appropriate CTI vendor APIs are available, a real-time transcript can be collected during the call and held in front-end memory, which then can be used at the end of the call.

{
    data: {
       agentTranscripts: array<{
            channel: string,
           text: string,
           offsetMs: number }> (optional),

      customerTranscripts: array<{
           channel: string,
           text: string,
           offsetMs: number }> (optional),

      combinedTranscripts: array<{
           channel: string, 
           text: string, 
           offsetMs: number }> (optional)

    },

    error: object<{
         isError: boolean, 
         message: string }> (optional)
    }
}

agentTranscripts:

An array of collected text transcripts for the agent's side of the conversation. Each element consists of the channel , text and offsetMS.

customerTranscripts:

An array of collected text transcripts for Customer's side of conversation. Each element consists of the channel , text and offsetMS.

combinedTranscripts:

An array of collected text transcripts for the whole conversation. Each element consists of the channel , text and offsetMS.

channel:

Either 'internal' or 'external'

text:

Actual speech to text transcript

offsetMs:

Offset in milliseconds from the conversation start time.

If the partner applications receives an error while collecting the call transcript from CTI backend, it can notify Service Guide about the error by including the "error" object in the payload instead of including the "data" object.

Error object has following properties:

• isError: Boolean representing whether or not an error occurred.
• message: An error code representing the type of error that occurred. Possible values are "TRANSCRIPTION_​FAILED".

Either only combinedTranscripts OR both agentTranscripts and customerTranscripts must be included in the payload.

The channel property should have one of these values, based on who the conversation owner is:

channel='internal'

All elements of agentTranscripts OR those elements in combinedTranscripts that belong to agent.

channel='external'

All elements of customerTranscripts OR those elements in combinedTranscripts that belong to customer.

To be invoked when the call wrap up has been completed on the CTI side and the Service Guide UI should be notified so that it can reset itself, making the agent available for the next call.

   {
     data: {
       callId: string
     },
     error: object<{
        isError: boolean,
        message: string
     }> (optional)
   }

callId:

A unique identifier for the call for which the wrapup was done.

If the partner applications receives an error while capturing the wrap up information on CTI side, it can notify Service Guide about the error by including the "error" object in the payload instead of including the "data" object.

Error object has following properties:

• isError: Boolean representing whether or not an error occurred.
• message: An error code representing the type of error that occurred. Possible values are "WRAPUP_​FAILED".

This operation should be invoked in response to the "logout" event to notify the Service Guide that the partner application has finished performing any cleanup in response to the "logout".