NAV
curl

Check widget availability

Check if chat is currently online for this widget. Please see the cURL tab to the right for an example.

GET /api/v1/chat/{widgetId}

Request Parameters

Data Type Description
widgetId String Unique identifier of the widget

Sample Request

Please see the cURL tab to the right for an example.

// NOTE: Make sure to replace the "{api_key}" below with your API key!

curl -X GET \
  https://www.snapengage.com/api/v1/chat/5286374d-5c92-419d-bcdb-b926d242b78b \
  -H 'x-api-key: {api_key}'

Response Parameters

Data Type Description
widgetId String Widget UUID from request.
online Boolean If this chat widget is available to start a chat.
emailRequired Boolean If an email address is required when starting a new chat.
messageRequired Boolean If the initial message is required when starting a new chat.
screenshotRequired Boolean If this chat widget requires a screenshot.

Success Response

200 OK

{
    "widgetId": "5286374d-5c92-419d-bcdb-b926d242b78b",
    "online": "true",
    "emailRequired": "false",
    "messageRequired": "false",
    "screenshotRequired": "false"
}

Error responses

Error Code Description
400 Invalid or missing parameter
401 Unauthorized – Invalid or no header x-api-key set
404 Not Found – Widget or Chat object not found (Empty response)
405 HTTP 405 Method Not Allowed - Something is wrong with the structure of your request.
500 Internal Server Error – Contact SnapEngage support if you continue to see this Response.

Poll for new chat message

Check for new chat messages, recommend interval no more than 1-2 seconds. Please see the cURL tab to the right for an example.

GET /api/v1/chat/poll/{caseId}

Request Parameters

Data Type Description
caseId String Unique identifier of chat session. (Obtained from Start New Chat API response: POST /api/v1/chat)
index Integer The start index of chats to return. Default is 0.
isTyping Boolean Is the visitor currently typing a message? Default is false.

Sample Request

Please see the cURL tab to the right for an example.

// NOTE: Make sure to replace the "{api_key}" below with your API key!

curl -X GET \
  https://www.snapengage.com/api/v1/chat/poll/f383eadb-a15e-4d13-bda2-6f3bf412de62 \
  -H 'x-api-key: {api_key}'

Response Parameters

Data Type Description
caseId String Unique identifier of chat session.
agentTyping Boolean Is true if the agent is currently typing a message.
messageList Array An array of messages.
↳index Integer Index of the chat message in the transcript.
↳type String Either “agent” or “system”.
↳author String The agent alias.
↳text String The message that was sent.

Success Response

200 OK

Please see the json tab to the right for an example.

{
    "caseId": "f383eadb-a15e-4d13-bda2-6f3bf412de62",
    "messageList": [
        {
            "index": 2,
            "type": "system",
            "author": "Sam",
            "text": "/NIC Sam "
        },
        {
            "index": 3,
            "type": "system",
            "author": "Sam",
            "text": "/CAL 1 "
        },
        {
            "index": 4,
            "type": "system",
            "author": "",
            "text": "/NFO Just a moment...<br> "
        },
        {
            "index": 6,
            "type": "system",
            "author": "Sam",
            "text": "/SYS EMTR false "
        },
        {
            "index": 7,
            "type": "system",
            "author": "Sam",
            "text": "/SYS GRCP -1 "
        },
        {
            "index": 8,
            "type": "system",
            "author": "Sam",
            "text": "/SYS WAGT 6%2CSorry%2520for%2520the%2520delay.%2520We%27re%2520working%2520on%2520getting%2520to%2520you%2520as%2520quickly%2520as%2520possible.%2520If%2520you%2520need%2520to%2520run%2C%2520please%2520feel%2520free%2520to%2520%5Bleave%2520us%2520a%2520message%5D "
        },
        {
            "index": 9,
            "type": "system",
            "author": "Sam",
            "text": "/SYS REAS 16 "
        },
        {
            "index": 10,
            "type": "system",
            "author": "Sam",
            "text": "/NIC Sam "
        },
        {
            "index": 11,
            "type": "system",
            "author": "Sam",
            "text": "/CAL 1 "
        },
        {
            "index": 12,
            "type": "agent",
            "author": "Sam",
            "text": "hi "
        },
        {
            "index": 14,
            "type": "agent",
            "author": "Sam",
            "text": "Ok, I can help you with that! "
        }
    ],
    "agentTyping": false
}

Send chat message

Update the chat with a new message or end the chat. Please see the cURL tab to the right for an example.

PUT /api/v1/chat

Request Parameters

Data Type Description
caseId Sting Required. Unique identifier of chat session. (Obtained from Start New Chat API response: POST /api/v1/chat)
messageType Integer Use 1 for normal message, 2 to close chat session.
messageBody String Text of chat message. (utf-8 URL encoded is recommended)

Sample Request

Please see the cURL tab to the right for an example.

// NOTE: Make sure to replace the "{api_key}" below with your API key!

curl -X PUT \
  'https://www.snapengage.com/api/v1/chat?caseId=a26503d8-4495-4147-acb4-d1a95ae744d5&messageType=1&messageBody=I%20need%20help%20finding%20shoes%21' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'x-api-key: {api_key}'

Response Parameters

Data Type Description
caseId String Unique identifier of chat session. (Obtained from Start New Chat API response: POST /api/v1/chat)
messageType Integer Use 1 for normal message, 2 to close chat session.
messageBody String Text of chat message. (utf-8 URL encoded is recommended)

Success Response

200 OK

Please see the json tab to the right for an example.

{
    "caseId": "a26503d8-4495-4147-acb4-d1a95ae744d5",
    "messageBody": "I need help finding shoes!",
    "messageType": "1"
}

Start new chat

Start a new Chat. Please see the cURL tab to the right for an example.

POST /api/v1/chat

Request Parameters

Data Type Description
widgetId String Required. Unique identifier of the widget.
email String (Required if emailRequired is true for chat widget) Visitor’s email address.
phone String Visitor’s phone number.
userAgent String Similar to web browser user agent string.
locale String Locale of this chat session. Example could be “en” or “en-GB”.
isOffline Boolean true/false – Open chat session or send message directly to email (offline). Default is false.
appVersionName String Name/Version of your application.
visitorMessage String (Required if messageRequired is true for chat widget) Initial visitor chat message.

Sample Request

Please see the cURL tab to the right for an example.

// NOTE: Make sure to replace the "{api_key}" below with your API key!

curl -X POST \
  'https://www.snapengage.com/api/v1/chat?widgetId=5286374d-5c92-419d-bcdb-b926d242b78b&[email protected]&phone=555-123-4567&userAgent=Mozilla/5.0%20%28Macintosh;%20Intel%20Mac%20OS%20X%2010_8_2%29%20AppleWebKit/537.17%20%28KHTML,%20like%20Gecko%29%20Chrome/24.0.1309.0%20Safari/537.17&locale=en&isOffline=false&appVersionName=My%20Mobile%20App&visitorMessage=hello' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'x-api-key: {api_key}'

Response Parameters

Data Type Description
caseId String Unique identifier of chat session.
widgetId String Unique identifier of chat widget.

Success Response

200 OK

Please see the json tab to the right for an example.

{
    "caseId": "ca5e3eca-8659-44a7-89fd-2f0b4dd71fa6",
    "widgetId": "5286374d-5c92-419d-bcdb-b926d242b78b"
}

Proactive Chat in Single Page Applications

Proactive Chat can be triggered by a URL change or a page refresh.

These kind of events can't be automatically tracked by SnapEngage, therefore we have worked on a solution and we have exposed a function by the name reInitProactiveRules(). Whenever there is a url change, call this function SnapEngageChat.reInitProactiveRules(). You can also bypass 'Proactive chat re-engagement delay' by calling the method like this reInitProactiveRules({force:true})

curl