Skip to main content

Open Conversation

Description:

This API can be used by the visitors to start a new conversation 

Request Payload:

  • app_id ​- To specify the portals app id of the brand. (Mandatory)
  • department_id ​​- To specify the ID of the conversation initiated department. (Mandatory)
  • question ​- To specify the visitor's question. (Mandatory)
  • customer_info ​- To specify the visitor's customer info. You can use this key to update data on the JS APIs 
  • custom_wait_time ​- To specify a custom waiting time for the conversation. The custom wait time can be mentioned using JS APIs. 
  • visitor.user_id - To specify any unique value associated with the visitor (Mandatory)
  • visitor.name - To specify the visitor's name. 
  • visitor.email - To specify the visitor's email address.
  • visitor.phone ​- To specify the visitor's phone number.
  • visitor.avuid ​​- An unique ID used to differentiate the chats associated with the specific visitor this ID is used in the get conversations API to get the conversations associated with the visitor. Example: 608d49f7-fc91-4df9-a556-660ad820a9d5
  • visitor.cvuid ​- To specify the visitor's cvuid (from customer through JS API). It can be used in the get conversations API to fetch the conversations associated with the visitor.
  • visitor.platform ​- To specify the visitor's platform (Ex: MacIntel)
  • visitor.current_page - To specify the visitor's current webpage.
  • visitor.page_title -To specify the visitor's current webpage title.
  • visitor.country_code - To specify the visitor's country code.
  • visitor.local_time_zone - To specify the visitor's time zone.
  • visitor.cookie_enabled - To specify the visitor's browser cookie setting information. 
  • visitor.java_enabled - To specify the visitor's browser java setting information.
  • visitor.screen - To specify the visitor's screen resolution.
  • visitor.color_code - To specify the visitor's color code.
  • visitor.flash_version - To specify the visitor's browser flash version.
  • visitor.js_version - To specify the visitor's browser JS version.
  • visitor.referrer - To specify the referrer.

Note: To use this API you must use an Org OAuth token. To know how to generate an Org OAuth token, please check our help guide here.

OAuth Scope:

SalesIQ.Conversations.CREATE

Request type: POST

UI View:

You can view the keys on the UI on the operator chat window by clicking on the info icon on the Visitor info widget.

URL:

Copiedhttps://{zohosalesiq_server_uri}/api/visitor/v1/{screen name}/conversations

Example:

Copiedhttps://salesiq.zoho.com/api/visitor/v1/zylkerinc/conversations

Payload:

Copied{
"visitor": {
    "user_id": "patricia@zylker.com",
    "name": "Patricia",
    "email": "patricia@zylker.com",
    "phone": "3132232231",
    "avuid": "608d49f7-fc91-4df9-a556-660ad820a9d5",
    "platform": "MacIntel",
    "color_code": "24",
    "cookie_enabled": "true",
    "current_page": "http://zylker.com/",
    "java_enabled": "true",
    "js_version": "1.7",
    "screen": "1436 * 877",
    "page_title": "zylker",
    "country_code": "US",
    "flash_version": "0.0.0",
    "local_time_zone": "GMT+0530 (IST)",
  "referrer": "http://zylker.com/"
},
"app_id": "430872000000002043",
"question": "hi there",
"department_id": "430872000000002013",
 "custom_wait_time": 100


 
}

Success Response

Copied{
    "url":"/api/visitor/v1/zylkerinc/conversations",
    "object":"conversations",
    "data":{
        "id":"d2e4771bec859eb6cdeccd9e347dd512076189d2ceb67633",
        "wms_chat_id":"LD_2243210259183736169_1681358420",
        "unread_chats":false,
        "question":"hi there",
        "department":{
            "id":"430872000000002013"
        },
        "last_modified_time":"1606470519005",
        "start_time":"1606470519005",
        "visitor":{
            "phone":"3132232231",
            "user_id":"patricia@zylker",
            "email":"patricia@zylker.com",
            "name":"Patricia",
            "country_code":"GB",
            "type":"contact",
            "chat_id":"0ae40a8eb62fc139ae71661959302d33ea195094089240380d28d8aba4258d4e94863c19b9ed1e9c",
        "chat_status":{
                "state_key":"waiting",
                "status_code":0,
                "state":1,
                "status_key":"open"
        },
        "reference_id":"1350"
    }
}