Skip Navigation
Expand
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

<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>
    <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>
   </soapenv:Header>
   <soapenv:Body>
      <v11:PostChatMessage>
         <v11:TransactionRequestData>
            <v11:ClientRequestTime>11:30:20</v11:ClientRequestTime>
            <v11:ClientTransactionID>2</v11:ClientTransactionID>
            <v11:SiteName>YourSiteName</v11:SiteName>
         </v11:TransactionRequestData>
         <v11:Body>This is a PostChatMessage message!</v11:Body>
      </v11:PostChatMessage>
   </soapenv:Body>
</soapenv:Envelope>

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:

<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>
    <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>
   </soapenv:Header>
   <soapenv:Body>
      <v11:TerminateChat>
         <v11:TransactionRequestData>
            <v11:ClientRequestTime>?</v11:ClientRequestTime>
            <v11:ClientTransactionID>2</v11:ClientTransactionID>
            <v11:SiteName>YourSiteName</v11:SiteName>
         </v11:TransactionRequestData>
      </v11:TerminateChat>
   </soapenv:Body>
</soapenv:Envelope>

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>


Related Links:

Chat APIs Developer Guide