Search

Chat API Example Chat Session

Answer ID 8129 | Last Review Date 01/27/2019

What is an example of a Chat API Chat session?

Environment:

Chat APIs

Resolution:

Below is a very simple, yet working (after you modify for your site), example of a Chat API Chat session. Although these calls to the Chat API should be made through code that would be generated from the wsdl, these are basic soap envelopes of a sample chat session that were sent through SoapUI, and are for illustration purposes only.

Note: To generate and run test soap calls, you can install the free version of SoapUI. Once installed, select File, New SOAP Project, and enter your site's chat WSDLs to load the requests for each. There are two WSDLs; one for requests to your site and another for requests to the chat server.

For Versions 17.5 and Older:
Site requests: http://<site>/cgi-bin/<interface>.cfg/services/chat_soap?wsdl
Server requests: http://<site>/cgi-bin/<interface>.cfg/services/chat_soap?wsdl=server

For Versions 17.8 and Newer:
Site requests: https://<vhostname>.custhelp.com/services/soap/connect/chat_soap?wsdl
Server requests: https://<vhostname>.custhelp.com/services/soap/connect/chat_soap?wsdl=server

Once the requests are generated from the WSDLs; the following requests can be made against the site:

GetChatOperatingHours
GetChatUrl

The following requests are made using information from the requests made against the site to the server:

PostChatMessage
RequestChat
RetrieveMessages
SendActivityChange
TerminateChat

Here is a high-level overview of the steps that happen:

--> GetChatUrl
Sent to endpoint of your chat_soap?wsdl.
<-- Returns a ChatUrlResponse, containing a ChatUrl, ChatToken and SiteName.

--> RequestChat
Sent to ChatUrl from previous step, pass in ChatToken and SiteName from previous step.
<-- Returns a RequestChatResponse containing a SessionID

--> RetrieveMessages
Sent to ChatUrl from previous step, pass in SessionID from previous step.
<-- Returns a RetrieveMessagesResponse containing messages

--> PostChatMessage
Sent to ChatUrl from previous step, pass in SessionID from previous step.
<-- Returns a PostChatMessageResponse containing messages

--> TerminateChat
Sent to ChatUrl from previous step, pass in SessionID from previous step.
<-- Returns a TerminateChatResponse confirming termination of chat

Step One: GetChatUrl

Request:

<env:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:rncm="urn:messages.chat.ws.rightnow.com/v1_2" xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ins0="urn:fault.ws.rightnow.com/v1_2">
   <env:Header>
     <ClientRequestHeader xmlns="urn:messages.chat.ws.rightnow.com/v1_2">
      <AppID>Sample Chat Client</AppID>
   </ClientRequestHeader>
   <wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
      <wsse:UsernameToken xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" wsu:Id="UsernameToken-1">
         <wsse:Username>YourUserID</wsse:Username>
         <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">XXXXX</wsse:Password>
         </wsse:UsernameToken>
      </wsse:Security>
   </env:Header>
   <env:Body>
     <rncm:GetChatUrl>
      <rncm:UrlType>ENDUSER</rncm:UrlType>
      <rncm:Version>1.2</rncm:Version>
   </rncm:GetChatUrl>
</env:Body>
</env:Envelope>

Response:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Header/>
   <soapenv:Body>
      <n0:GetChatUrlResponse xmlns:n0="urn:messages.chat.ws.rightnow.com/v1_2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
         <n0:GetChatUrlResult>
            <n0:ChatUrl>CHAT_URL_WILL_BE_HERE</n0:ChatUrl>
            <n0:ChatToken>1234a5b6-c789-01d2-345-678ef90a1bc2</n0:ChatToken>
            <n0:SiteName>YOUR_SITE_NAME</n0:SiteName>
         </n0:GetChatUrlResult>
      </n0:GetChatUrlResponse>
   </soapenv:Body>
</soapenv:Envelope>

(make note of the ChatUrl, ChatToken, and SiteName. You'll be using those in another call)

Step Two: RequestChat

(Sent to CHAT_URL_WILL_BE_HERE, returned above)

Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:v1="urn:messages.common.chat.ws.rightnow.com/v1" xmlns:v11="urn:messages.enduser.chat.ws.rightnow.com/v1">
   <soapenv:Header>
      <v1:ChatClientInfoHeader>
         <v1:AppID>Sample Chat Client</v1:AppID>
      </v1:ChatClientInfoHeader>
      <wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" soapenv:mustUnderstand="1">
         <wsse:UsernameToken xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" wsu:Id="UsernameToken-3902281">
            <wsse:Username>YourUserName</wsse:Username>
            <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">XXXXX</wsse:Password>
         </wsse:UsernameToken>
      </wsse:Security>
   </soapenv:Header>
   <soapenv:Body>
      <v11:RequestChat>
         <v11:TransactionRequestData>
            <v11:ClientRequestTime>2015-03-07 11:34:00</v11:ClientRequestTime>
            <v11:ClientTransactionID>2</v11:ClientTransactionID>
            <v11:SiteName>YOUR_SITE_NAME</v11:SiteName>
         </v11:TransactionRequestData>
         <v11:CustomFields>
            <ObjectType>
               <TypeName>ContactCustomFields</TypeName>
            </ObjectType>
            <v1:GenericFields dataType="OBJECT" name="c">
               <DataValue>
                  <ObjectValue>
                     <ObjectType>
                        <TypeName>IncidentCustomFieldsc</TypeName>
                     </ObjectType>
                     <GenericFields dataType="STRING" name="priority">
                        <DataValue>
                           <StringValue>very high</StringValue>
                        </DataValue>
                     </GenericFields>
                  </ObjectValue>
               </DataValue>
            </v1:GenericFields>
         </v11:CustomFields>
         <v11:CustomerInformation>
            <v1:EMailAddress>name@email.invalid</v1:EMailAddress>
            <v1:FirstName>First</v1:FirstName>
            <v1:LastName>Last</v1:LastName>
            <v1:InterfaceID>
               <v1:ID id="1"/>
            </v1:InterfaceID>
         </v11:CustomerInformation>
         <v11:ChatSessionToken>1234a5b6-c789-01d2-345-678ef90a1bc2</v11:ChatSessionToken> <-- Must match the Token above!
      </v11:RequestChat>
   </soapenv:Body>
</soapenv:Envelope>

Response:

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
   <S:Body>
      <ns3:RequestChatResponse xmlns="urn:messages.common.chat.ws.rightnow.com/v1" xmlns:ns2="urn:messages.uq.chat.ws.rightnow.com/v1" xmlns:ns3="urn:messages.enduser.chat.ws.rightnow.com/v1" xmlns:ns4="urn:faults.chat.ws.rightnow.com/v1">
         <ns3:TransactionResponseData>
            <ns3:ServiceStartTime>2015-11-10T18:41:12.654Z</ns3:ServiceStartTime>
            <ns3:ServiceFinishTime>2015-11-10T18:41:13.086Z</ns3:ServiceFinishTime>
            <ns3:ClientID>123</ns3:ClientID>
            <ns3:ClientTransactionID>2</ns3:ClientTransactionID>
         </ns3:TransactionResponseData>
         <ns3:EngagementID id="123"/>
         <ns3:CancelledSurveyID id="0"/>
         <ns3:CompletedSurveyID id="0"/>
         <ns3:ResultType>SUCCESS</ns3:ResultType>
         <ns3:SessionID>12a3bcdefghi4jk56lmn7o8pq</ns3:SessionID> <--Will be used in future calls
      </ns3:RequestChatResponse>
   </S:Body>
</S:Envelope>

Step Three: RetrieveMessages

Request:

<env:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:wsdl="urn:messages.enduser.chat.ws.rightnow.com/v1" xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
  <env:Header>
    <ChatClientInfoHeader xmlns="urn:messages.common.chat.ws.rightnow.com/v1">
      <AppID>Sample Chat Client</AppID>
      <SessionID>12a3bcdefghi4jk56lmn7o8pq</SessionID>
    </ChatClientInfoHeader>
    <wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
      <wsse:UsernameToken xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" wsu:Id="UsernameToken-1">
        <wsse:Username>YourUserName</wsse:Username>
        <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">XXXXX</wsse:Password>
      </wsse:UsernameToken>
    </wsse:Security>
  </env:Header>
  <env:Body>
    <wsdl:RetrieveMessages>
      <TransactionRequestData>
        <ClientRequestTime>11:30:20</ClientRequestTime>
        <ClientTransactionID>2</ClientTransactionID>
        <SiteName>YourSiteName</SiteName>
      </TransactionRequestData>
    </wsdl:RetrieveMessages>
  </env:Body>
</env:Envelope>

Response:

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
   <S:Body>
      <ns3:RetrieveMessagesResponse xmlns="urn:messages.common.chat.ws.rightnow.com/v1" xmlns:ns2="urn:messages.uq.chat.ws.rightnow.com/v1" xmlns:ns3="urn:messages.enduser.chat.ws.rightnow.com/v1" xmlns:ns4="urn:faults.chat.ws.rightnow.com/v1">
         <ns3:TransactionResponseData>
            <ns3:ClientRequestTime/>
            <ns3:ServiceStartTime>2015-11-10T18:42:47.019Z</ns3:ServiceStartTime>
            <ns3:ServiceFinishTime>2015-11-10T18:42:47.033Z</ns3:ServiceFinishTime>
            <ns3:ClientID>860</ns3:ClientID>
            <ns3:ClientTransactionID>2</ns3:ClientTransactionID>
         </ns3:TransactionResponseData>
         <ns3:SystemMessages>
            <ns3:RNChatParticipantAddedMessage>
               <CreatedTime>2015-11-10T18:41:31.176Z</CreatedTime>
               <ns3:Name>First Last</ns3:Name>
               <ns3:Greeting>Hi, my name is Joe Smith. How may I help you?</ns3:Greeting>
               <ns3:ClientID>123</ns3:ClientID>
               <ns3:Role>LEAD</ns3:Role>
            </ns3:RNChatParticipantAddedMessage>
            <ns3:RNChatMessagePostedMessage>
               <CreatedTime>2015-11-10T18:42:01.645Z</CreatedTime>
               <ns3:Body>test response</ns3:Body>
               <ns3:ClientID>123</ns3:ClientID>
            </ns3:RNChatMessagePostedMessage>
         </ns3:SystemMessages>
      </ns3:RetrieveMessagesResponse>
   </S:Body>
</S:Envelope>

Step Four: PostChatMessage

Request

Response

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
   <S:Body>
      <ns3:PostChatMessageResponse xmlns="urn:messages.common.chat.ws.rightnow.com/v1" xmlns:ns2="urn:messages.uq.chat.ws.rightnow.com/v1" xmlns:ns3="urn:messages.enduser.chat.ws.rightnow.com/v1" xmlns:ns4="urn:faults.chat.ws.rightnow.com/v1">
         <ns3:TransactionResponseData>
            <ns3:ClientRequestTime/>
            <ns3:ServiceStartTime>2015-11-10T20:23:44.553Z</ns3:ServiceStartTime>
            <ns3:ServiceFinishTime>2015-11-10T20:23:44.563Z</ns3:ServiceFinishTime>
            <ns3:ClientID>123</ns3:ClientID>
            <ns3:ClientTransactionID>2</ns3:ClientTransactionID>
         </ns3:TransactionResponseData>
      </ns3:PostChatMessageResponse>
   </S:Body>
</S:Envelope>

Step 5: TerminateChat

Request:

Response:

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
   <S:Body>
      <ns3:TerminateChatResponse xmlns="urn:messages.common.chat.ws.rightnow.com/v1" xmlns:ns2="urn:messages.uq.chat.ws.rightnow.com/v1" xmlns:ns3="urn:messages.enduser.chat.ws.rightnow.com/v1" xmlns:ns4="urn:faults.chat.ws.rightnow.com/v1">
         <ns3:TransactionResponseData>
            <ns3:ServiceStartTime>2015-11-10T20:25:16.090Z</ns3:ServiceStartTime>
            <ns3:ServiceFinishTime>2015-11-10T20:25:16.127Z</ns3:ServiceFinishTime>
            <ns3:ClientID>123</ns3:ClientID>
            <ns3:ClientTransactionID>2</ns3:ClientTransactionID>
         </ns3:TransactionResponseData>
      </ns3:TerminateChatResponse>
   </S:Body>
</S:Envelope>

Search

What is an example of a Chat API Chat session?

Was this answer helpful?

Still have questions?

Available Languages for this Answer:

Related Answers

Login