NAV

Introduction

ChatPirate is the simplest live chat software that allows you chat with your visitors in real-time, collect leads, and increase sales, all while having unlimited agents, full customization, and easy integration. With this documentation we address the most common integration and customization use cases to help you tailor your ChatPirate live chat to your needs. Some of the use cases include automation through REST API, hiding the widget when offline, creation of custom-looking chat buttons, integration with Google Analytics, and more!

REST API

Introduction

The ChatPirate REST API is designed to be RESTful compliant with JSON responses. This means that the API communicate over HTTP (including the use of HTTP verbs). The API allows you to create, read, update and delete (CRUD) resources. Also, each single resource has a URI (Unique Resource Identifier) to help access its properties.

The CRUD methods on the ChatPirate API correspond to HTTP’s verbs POST, GET, PATCH and DELETE, so that depending on the resources and providing you have the access rights.

Authentication

In order to use the ChatPirate API you have to authenticate using HTTP Basic Auth. HTTP Basic Auth requires you to provide a username and a password for each API request. The username is your email and the password is your password. Optionally you can login by token which is generated for you after registration.

All requests must be made over HTTPS.

Status codes

ChatPirate uses standard HTTP status codes to communicate errors

Code Description
200 Success – The request was successful
401 Unauthorized – Invalid Credentials
403 Forbidden – Your credentials are valid but you don’t have access to the requested resource
404 Not Found – The resource with the specified ID you are trying to reach does not exist
422 Unprocessable Entity – A validation error occurred
50X Internal Server Error – Something went wrong on our end

Register

Create new account

HTTP Request

$ curl -X POST \
    'https://app.chatpirate.com/api/v1/register' \
    -H 'Content-Type: application/json' \
    -d '{
        "companyName": "ACME",
        "website": "http://acme.org",
        "createdType": "joomla",
        "operatorName": "Wile E. Coyote",
        "email": "wille.e.coyote@acme.org",
        "password": "qwerty123",
        "timezone": "UTC"
    }'

POST https://app.chatpirate.com/api/v1/register

Example response

{
    "message":"Account successfully created",
    "data":{
        "operatorId":1,
        "companyId":1963030101,
        "name":"Wile E. Coyote",
        "jobTitle":"",
        "avatar":"",
        "email":"wille.e.coyote@acme.org",
        "token":"965854ffa0e4196d9adcebdfdccb95fc4ba4974598e6cce24bac578eea59a818"
    }
}

Request Parameters

Parameter Required Description
companyName yes Company name

Size range: between: 3,30
website yes Website url
createdType no How company was created

Default value: website

Allowed values: website, wordpress, joomla, magento, prestashop, weebly, shopify, drupal, wix
employeesNumber no Number of emnployees

Allowed values: 1-5, 6-10, 11-20, 20-100, >100
operatorName yes Operator name

Size range: between: 2,20
email yes Operator email

Size range: unique
password yes Operator password

Size range: min:6
timezone no The field under validation must be a valid `timezone` identifier according to the DateTimeZone::listIdentifiers

Default value: UTC

Check if operator exists

HTTP Request

$ curl https://app.chatpirate.com/api/v1/register/checkOperator/wille.e.coyote@acme.org

GET https://app.chatpirate.com/api/v1/register/checkOperator/{email}

Example response

{
    "error":{
        "message":{
            "email":["The email has already been taken."]
        },
        "status_code":422
    }
}

Retrieve token

HTTP Request

$ curl 'https://app.chatpirate.com/api/v1/register/getToken' \
    -H 'Authorization: wille.e.coyote@acme.org::qwerty123'

Example response

{
    "message":"Access granted",
    "data":{
        "companyId":1963030101,
        "email":"wille.e.coyote@acme.org",
        "token":"965854ffa0e4196d9adcebdfdccb95fc4ba4974598e6cce24bac578eea59a818"
    }
}

GET https://app.chatpirate.com/api/v1/register/getToken

Request Parameters

Parameter Required Description
Authorization yes email::password

Login by token

HTTP Request

$ curl 'https://app.chatpirate.com/api/v1/register/loginByTokenHeader' \
    -H 'Authorization: wille.e.coyote@acme.org::965854ffa0e4196d9adcebdfdccb95fc4ba4974598e6cce24bac578eea59a818'

Example response

{
    "message":"Access granted",
    "data":{
      "companyId":1963030101,
      "email":"wille.e.coyote@acme.org",
      "token":"965854ffa0e4196d9adcebdfdccb95fc4ba4974598e6cce24bac578eea59a818"
    }
}

GET https://app.chatpirate.com/api/v1/register/loginByTokenHeader

Or

GET https://app.chatpirate.com/api/v1/register/loginByToken/{email}/{token}

Operators

List all operators

If Your permission are:

HTTP Request

$ curl 'https://app.chatpirate.com/api/v1/operator' \
    -u 'wille.e.coyote@acme.org:qwerty123'

GET https://app.chatpirate.com/api/v1/operator

Example response

{
    "data":[
        {
            "operatorId":1,
            "name":"Wile E. Coyote",
            "jobTitle":"",
            "email":"wille.e.coyote@acme.org"
        }
    ],
    "paginator":{
        "totalCount":1,
        "totalPage":1,
        "currentPage":1,
        "limit":50
    }
}

Query Parameters

Parameter Required Description
limit no Number of operators per page

Default value: 50
page no Page number

Default value: 1

Basic details list

$ curl 'https://app.chatpirate.com/api/v1/operator/basic' \
    -u 'wille.e.coyote@acme.org:qwerty123'

GET https://app.chatpirate.com/api/v1/operator/basic

Example response

{
    "message":"Success",
    "data":[
        {
            "operatorId":2,
            "avatar":"",
            "name":"The Road Runner",
            "jobTitle":""
        },
        {
            "operatorId":1,
            "avatar":"",
            "name":"Wile E. Coyote",
            "jobTitle":"The Coyote"
        }
    ]
}

Get operator details

If Your permission are:

HTTP Request

$ curl \
    'https://app.chatpirate.com/api/v1/operator/1' \
    -u 'wille.e.coyote@acme.org:qwerty123'

GET https://app.chatpirate.com/api/v1/operator/{id}

Example response

{
    "data":{
        "operatorId":1,
        "companyId":1963030101,
        "owner":true,
        "name":"Wile E. Coyote",
        "jobTitle":"",
        "email":"wille.e.coyote@acme.org",
        "language":"en",
        "avatar":"",
        "tutorial":true,
        "loginAsBusy":false,
        "acceptingChats":true,
        "chatsLimit":5,
        "permission":[
            "chat",
            "archive",
            "reports",
            "settingsIntegration",
            "settingsTheme",
            "settingsTools",
            "settingsTeam"
        ],
        "notifications":{
            "showMessageText":true,
            "sounds":true,
            "soundFile":"sound-1"
        },
        "ipRestriction":[],
        "timezone":"UTC"
    }
}

Get details of your account

Useful endpoint when you have no idea what {id} your account have.

$ curl 'https://app.chatpirate.com/api/v1/operator/whoami' \
    -u 'wille.e.coyote@acme.org:qwerty123'

GET https://app.chatpirate.com/api/v1/operator/whoami

Example response

{
    "data":{
        "operatorId":1,
        "companyId":1963030101,
        "owner":true,
        "name":"Wile E. Coyote",
        "jobTitle":"",
        "email":"wille.e.coyote@acme.org",
        "language":"en",
        "avatar":"",
        "tutorial":true,
        "loginAsBusy":false,
        "acceptingChats":true,
        "chatsLimit":5,
        "permission":[
            "chat",
            "archive",
            "reports",
            "settingsIntegration",
            "settingsTheme",
            "settingsTools",
            "settingsTeam"
        ],
        "notifications":{
            "showMessageText":true,
            "sounds":true,
            "soundFile":"sound-1"
        },
        "ipRestriction":[],
        "timezone":"UTC"
    }
}

Create new operator

If Your operator permission are:

HTTP Request

$ curl -X POST \
    'https://app.chatpirate.com/api/v1/operator' \
    -u 'wille.e.coyote@acme.org:qwerty123' \
    -H 'Content-Type: application/json' \
    -d '{
        "name": "The Road Runner",
        "email": "the.road.runner@acme.org",
        "password": "qwerty123"
    }'

POST https://app.chatpirate.com/api/v1/operator

Example response

{
    "message":"Operator successfully created",
    "data":{
        "operatorId":2,
        "companyId":1963030101,
        "owner":false,
        "name":"The Road Runner",
        "jobTitle":"",
        "email":"the.road.runner@acme.org",
        "language":"en",
        "avatar":"",
        "tutorial":true,
        "loginAsBusy":false,
        "acceptingChats":true,
        "chatsLimit":5,
        "permission":[
            "chat",
            "archive",
            "reports",
            "settingsIntegration",
            "settingsTheme",
            "settingsTools",
            "settingsTeam"
        ],
        "notifications":{
            "showMessageText":true,
            "sounds":true,
            "soundFile":"sound-1"
        },
        "ipRestriction":[],
        "timezone":"UTC"
    }
}

Request Parameters

Parameter Required Description
name yes Operator name

Size range: between:2,20
email yes Operator email

Size range: unique
password yes Operator password
timezone no The field under validation must be a valid `timezone` identifier according to the DateTimeZone::listIdentifiers

Default value: UTC

Update operator

If Your operator permission are:

HTTP Request

$ curl -X PATCH \
    'https://app.chatpirate.com/api/v1/operator/1' \
    -u 'wille.e.coyote@acme.org:qwerty123' \
    -H 'Content-Type: application/json' \
    -d '{
        "jobTitle": "The Coyote"
    }'

PATCH https://app.chatpirate.com/api/v1/operator/{id}

Example response

{
    "message":"Operator successfully updated",
    "data":{
        "operatorId":1,
        "companyId":1963030101,
        "owner":true,
        "name":"Wile E. Coyote",
        "jobTitle":"The Coyote",
        "email":"wille.e.coyote@acme.org",
        "language":"en",
        "avatar":"",
        "tutorial":true,
        "loginAsBusy":false,
        "acceptingChats":true,
        "chatsLimit":5,
        "permission":[
            "chat",
            "archive",
            "reports",
            "settingsIntegration",
            "settingsTheme",
            "settingsTools",
            "settingsTeam"
        ],
        "notifications":{
            "showMessageText":true,
            "sounds":true,
            "soundFile":"sound-1"
        },
        "ipRestriction":[],
        "timezone":"UTC"
    }
}

Request Parameters

Parameter Required Type Description
name no String Operator name

Size range: between:2,20
jobTitle no String Operator job title

Size range: max:30
email no Email Operator email
password no String Operator password

Size range: min:6
loginAsBusy no
Boolean Login operator as busy
acceptingChats no Boolean Accepting chats
chatsLimit no Numeric Chats limit

Size range: max:10
language no String Operator language, standard: ISO_3166-1 alfa-2

Allowed values: en
timezone no Timezone The field under validation must be a valid `timezone` identifier according to the DateTimeZone::listIdentifiers

Default value: UTC

Delete an operator

Deleting operator require settingsTeam without settingsTeam:self permission. Deleting account in which you are logged in, or owner account is not possible and will throw an error.

HTTP Request

$ curl -X DELETE \
    'https://app.chatpirate.com/api/v1/operator/1' \
    -u 'wille.e.coyote@acme.org:qwerty123'

DELETE https://app.chatpirate.com/api/v1/operator/{id}

Example response

{
    "message":"Operator deleted"
}

Restore an operator

Restoring deleted operator require settingsTeam without settingsTeam:self permission.

HTTP Request

$ curl \
    'https://app.chatpirate.com/api/v1/operator/2/restore' \
    -u 'wille.e.coyote@acme.org:qwerty123'

GET https://app.chatpirate.com/api/v1/operator/{id}/restore

Example response

{
    "message":"Operator restored",
    "data":{
        "operatorId":2,
        "companyId":1963030101,
        "owner":false,
        "name":"The Road Runner",
        "jobTitle":"",
        "email":"the.road.runner@acme.org",
        "language":"en",
        "avatar":"",
        "tutorial":true,
        "loginAsBusy":false,
        "acceptingChats":true,
        "chatsLimit":5,
        "permission":[
            "chat",
            "archive",
            "reports",
            "settingsIntegration",
            "settingsTheme",
            "settingsTools",
            "settingsTeam"
        ],
        "notifications":{
            "showMessageText":true,
            "sounds":true,
            "soundFile":"sound-1"
        },
        "ipRestriction":[],
        "timezone":"UTC"
    }
}

Update permissions

Permissions permanently added:

Updating operators permissions require settingsTeam without settingsTeam:self permission.

HTTP Request

$ curl -X PATCH \
    'https://app.chatpirate.com/api/v1/operator/2/updatePermission' \
    -H 'Content-Type: application/json' \
    -u 'wille.e.coyote@acme.org:qwerty123' \
    -d '{
        "permission": [
            "settingsTeam:self"
        ]
    }'

PATCH https://app.chatpirate.com/api/v1/operator/{id}/updatePermission

Example response

{
    "message":"Permission successfully updated",
    "data":{
        "permission":[
            "settingsTeam:self",
            "archive",
            "settingsTeam"
        ]
    }
}

Request Parameters

Parameter Type Description
permission Array.<String> Size range: max:30

Allowed values: chat, archive, archive:self, reports, settingsIntegration, settingsTheme, settingsTools, settingsTeam, settingsTeam:self

Desktop notifications

If Your operator permission are:

HTTP Request

$ curl -X PATCH \
    'https://app.chatpirate.com/api/v1/operator/2/updateNotifications' \
    -H 'Content-Type: application/json' \
    -u 'wille.e.coyote@acme.org:qwerty123' \
    -d '{
        "showMessageText": false,
        "sounds": true,
        "soundFile": "sound-2"
    }'

PATCH https://app.chatpirate.com/api/v1/operator/{id}/updateNotifications

Example response

{
    "message":"Notifications successfully updated",
    "data":{
        "showMessageText":false,
        "sounds":true,
        "soundFile":"sound-2"
    }
}

Request Parameters

Parameter Type Description
showMessageText Boolean Enabled/disabled text in desktop notifications

Default value: true
sounds Boolean Enabled/disabled sound

Default value: true
soundFile String Sound type

Default value: sound-1

Allowed values: sound-1, sound-2, sound-3, sound-4

IP restriction

If Your operator permission are:

HTTP Request

$ curl -X PATCH \
    'https://app.chatpirate.com/api/v1/operator/2/updateIpRestriction' \
    -H 'Content-Type: application/json' \
    -u 'wille.e.coyote@acme.org:qwerty123' \
    -d '{ "ipRestriction": ["192.168.1.1"] }'

PATCH https://app.chatpirate.com/api/v1/operator/{id}/updateIpRestriction

Example response

{
    "message":"IpRestriction successfully updated",
    "data":{
        "ipRestriction":["192.168.1.1"]
    }
}

Request Parameters

Parameter Type Description
ipRestriction Array.<String> List of restricted IPs

Size range: max:20

Get locales

HTTP Request

$ curl \
    'https://app.chatpirate.com/api/v1/operator/showLanguage' \
    -u 'wille.e.coyote@acme.org:qwerty123'

GET https://app.chatpirate.com/api/v1/operator/showLanguage

Example response

{
    "message":"Success",
    "data":{
        "navigator_chat":"CHAT",
        "navigator_traffic":"TRAFFIC",
        "navigator_archive":"ARCHIVE",
        "navigator_statistics":"STATISTICS",
        "navigator_settings":"SETTINGS",
        "navigator_integrations":"INTEGRATIONS",
        "navigator_customize":"CUSTOMIZE",

        // ..

    }
}

Company

Get company details

HTTP Request

$ curl 'https://app.chatpirate.com/api/v1/company' \
    -u 'wille.e.coyote@acme.org:qwerty123'

GET https://app.chatpirate.com/api/v1/company

Example response

{
    "data":{
        "companyId":1963030101,
        "websites":[
            "http://acme.org"
        ],
        "name":"ACME",
        "banned":false,
        "onboarding":true,
        "createdType":"joomla",
        "billingPlan":{
            "agents":100,
            "type":"trial",
            "billingsCycle":1,
            "totalCost":0,
            "expire":"2016-05-18T14:08:23+0000",
            "preorder":false,
            "limits":[
                "permission",
                "ip",
                "branding_enabled"
            ]
        },
        "tags":[
            "sales",
            "spam",
            "support"
        ],
        "timezone":"UTC"
    }
}

Update company details

HTTP Request

$ curl -X PATCH \
    'https://app.chatpirate.com/api/v1/company' \
    -u 'wille.e.coyote@acme.org:qwerty123' \
    -d '{ "name": "Acme Corporation" }'

PATCH https://app.chatpirate.com/api/v1/company

Example response

{
    "message":"Company successfully updated",
    "data":{
        "companyId":1963030101,
        "websites":[
            "http://acme.org"
        ],
        "name":"Acme Corporation",
        "banned":false,
        "onboarding":true,
        "createdType":"joomla",
        "billingPlan":{
            "agents":100,
            "type":"trial",
            "billingsCycle":1,
            "totalCost":0,
            "expire":"2016-05-18T14:08:23+0000",
            "preorder":false,
            "limits":[
                "permission",
                "ip",
                "branding_enabled"
            ]
        },
        "tags":[
            "sales",
            "spam",
            "support"
        ],
        "timezone":"UTC"
    }
}
Parameter Type Description
name String Company name
websites Array List of websites
onboarding Boolean Turn on/off onboarding
tags Array.<String> Defined tags

Archives

Get list of chats

HTTP Request

$ curl 'https://app.chatpirate.com/api/v1/archive' \
    -u 'wille.e.coyote@acme.org:qwerty123'

GET https://app.chatpirate.com/api/v1/archive

Example response

{
    "data":[
        {
            "talkId": 3,
            "companyId":1963030101,
            "sectionId":0,
            "startTime":"2016-05-05T14:11:32+0000",
            "duration":666,
            "responseTime":10,
            "status":"user_cancelled",
            "unreadedMessages":0,
            "talkRate":0
        },
        {
            "talkId": 2,
            "companyId":1963030101,
            "sectionId":0,
            "startTime":"2016-05-05T13:34:09+0000",
            "duration":1150,
            "responseTime":0,
            "status":"user_cancelled",
            "unreadedMessages":0,
            "talkRate":0
        },
        {
            "talkId": 1,
            "companyId":1963030101,
            "sectionId":0,
            "startTime":"2016-05-05T13:30:36+0000",
            "duration":97,
            "responseTime":0,
            "status":"user_cancelled",
            "unreadedMessages":1,
            "talkRate":0
        }
    ],
    "paginator":{
        "totalCount":3,
        "totalPage":1,
        "currentPage":1,
        "limit":10
    }
}

Query Parameters

Parameter Required Type Description
limit no Number Number of chats per page

Default value: 10

Size range: max:20
page no Number Page number

Default value: 1
dateFrom no Date Beginning date

Format: Y-m-d H:i:s

Example: 2015-10-01 00:00:00

Default value: the beginning of time
dateTo no Date End date

Format: Y-m-d H:i:s

Example: 2015-10-01 00:00:00

Default value: now
operatorId no Number Chats for specific operator
sort no String Sort result by createdAt

Default value: desc

Allowed values: asc, desc

include no Array Include extra data

Allowed values: messages, firstMessage, operators, user

Get details of single chat

If Your operator permission are:

HTTP Request

$ curl 'https://app.chatpirate.com/api/v1/archive/1' \
    -u 'wille.e.coyote@acme.org:qwerty123'

GET https://app.chatpirate.com/api/v1/archive/{id}

Example response

{
    "message":"Success",
    "data":{
        "talkId": 1,
        "companyId":1963030101,
        "sectionId":0,
        "startTime":"2016-05-05T13:30:36+0000",
        "duration":97,
        "responseTime":0,
        "status":"user_cancelled",
        "unreadedMessages":1,
        "talkRate":0
    }
}

Update chat tags

If Your operator permission are:

HTTP Request

$ curl -X PATCH \
    'https://app.chatpirate.com/api/v1/archive/1/updateTags' \
    -u 'wille.e.coyote@acme.org:qwerty123' \
    -H 'Content-Type: application/json' \
    -d '{ "tags": ["spam"] }'

PATCH https://app.chatpirate.com/api/v1/archive/{id}/updateTags

Example response

{
    "message":"Tags successfully updated",
    "data":{
        "talkId":1,
        "tags":["spam"]
    }
}

Request Parameters

Parameter Type Description
tags Array.<String> Size range: max:10

Remove chat(s)

If Your operator permission are:

HTTP Request

Remove single chat

$ curl -X DELETE \
    'https://app.chatpirate.com/api/v1/archive/1' \
    -u 'wille.e.coyote@acme.org:qwerty123'

Remove list of chats

$ curl -X DELETE \
    'https://app.chatpirate.com/api/v1/archive' \
    -u 'wille.e.coyote@acme.org:qwerty123' \
    -H 'Content-Type: application/json' \
    -d '{ "talks": [1, 2, 3] }'

DELETE https://app.chatpirate.com/api/v1/archive/{id}

Example response

{
    "message":"Talk deleted"
}

Request Parameters

Parameter Required Type Description
talk no Number Chat {id}
talks no Array.<Numbers> Chats {id}s

Send chat transcript

If Your operator permission are:

HTTP Request

$ curl -X POST \
    'https://app.chatpirate.com/api/v1/archive/1/sendTranscript' \
    -u 'wille.e.coyote@acme.org:qwerty123' \
    -H 'Content-Type: application/json' \
    -d '{ "emails": "the.road.runner@acme.org, wille.e.coyote@acme.org" }'

POST https://app.chatpirate.com/api/v1/archive/{id}/sendTranscript

Example response

{
    "message":"Email successfully sent",
    "data":{
        "talkId":1,
        "emails":[
            "the.road.runner@acme.org",
            "wille.e.coyote@acme.org"
        ]
    }
}

Request Parameters

Parameter Type Description
email String List of emails separated by commas

Chat

Get list of active chats

HTTP Request

$ curl 'https://app.chatpirate.com/api/v1/talk' \
    -u 'wille.e.coyote@acme.org:qwerty123'

GET https://app.chatpirate.com/api/v1/talk

Example response

{
    "message":"Success",
    "data":[
        {
            "talkId":1,
            "companyId":1963030101,
            "sectionId":0,
            "startTime":"2016-05-05T13:34:09+0000",
            "duration":0,
            "responseTime":0,
            "status":"active",
            "unreadedMessages":1,
            "talkRate":0,
            "metadata":{
                "url":"https://acme.org/",
                "params":[]
            },
            "invitation":[],
            "tags":[],
            "messages":[
                {
                    "time":"2016-05-05T13:34:09+0000",
                    "authorId":1,
                    "authorType":"operator",
                    "message":"Welcome, how can I help you?"
                },
                {
                    "time":"2016-05-05T13:34:20+0000",
                    "authorId":"e4d55921-61ec-4777-8d61-a4c35d9e8b4d",
                    "authorType":"user",
                    "message":"Beep! Beep!"
                }
            ]
        }
    ]
}

Get details of single chat

HTTP Request

$ curl 'https://app.chatpirate.com/api/v1/talk/1' \
    -u 'wille.e.coyote@acme.org:qwerty123'

GET https://app.chatpirate.com/api/v1/talk/{id}

Example response

{
    "message":"Success",
    "data":{
        "talkId":1,
        "companyId":1963030101,
        "sectionId":0,
        "startTime":"2016-05-05T13:34:09+0000",
        "duration":0,
        "responseTime":0,
        "status":"active",
        "unreadedMessages":1,
        "talkRate":0,
        "metadata":{
            "url":"https://acme.org/",
            "params":[]
        },
        "invitation":[],
        "tags":[],
        "messages":[
            {
                "time":"2016-05-05T13:34:09+0000",
                "authorId":1,
                "authorType":"operator",
                "message":"Welcome, how can I help you?"
            },
            {
                "time":"2016-05-05T13:34:20+0000",
                "authorId":"e4d55921-61ec-4777-8d61-a4c35d9e8b4d",
                "authorType":"user",
                "message":"Beep! Beep!"
            }
        ]
    }
}

Clear unread messages

HTTP Request

$ curl -X PATCH \
    'https://app.chatpirate.com/api/v1/talk/1/clearUnreadMessages' \
    -u 'wille.e.coyote@acme.org:qwerty123'

PATCH https://app.chatpirate.com/api/v1/talk/{id}/clearUnreadMessages

Example response

{
    "message":"Talk successfully updated",
    "data":{
        "talkId":1
    }
}

Ticket

Get list of tickets

HTTP Request

$ curl 'https://app.chatpirate.com/api/v1/ticket' \
    -u 'wille.e.coyote@acme.org:qwerty123'

GET https://app.chatpirate.com/api/v1/ticket

Example response

{
    "data":[
        {
            "ticketId":1,
            "companyId":1963030101,
            "visitor":{
                "email":"the.road.runner@acme.org",
                "message":"Beep! Beep!"
            },
            "metadata":{
                "url":"https://cdn.chatpirate.com/preview.html?l=1963030101"
            },
            "read":false,
            "createdAt":"2016-05-06T07:26:24+0000"
        }
    ],
    "paginator":{
        "totalCount":1,
        "totalPage":1,
        "currentPage":1,
        "limit":10
    }
}

Query Parameters

Parameter Required Description
limit no Number of tickets per page

Default value: 10

Size range: max:20
page no Page number

Default value: 1
dateFrom no Beginning date

Format: Y-m-d H:i:s

Example: 2015-10-01 00:00:00

Default value: the beginning of time
dateTo no End date

Format: Y-m-d H:i:s

Example: 2015-10-01 00:00:00

Default value: now
sort no Sort result by createdAt

Default value: desc

Allowed values: asc, desc

Get details of single ticket

HTTP Request

$ curl 'https://app.chatpirate.com/api/v1/ticket/1' \
    -u 'wille.e.coyote@acme.org:qwerty123'

GET https://app.chatpirate.com/api/v1/ticket/{id}

Example response

{
    "message":"Success",
    "data":{
        "ticketId":1,
        "companyId":1963030101,
        "visitor":{
            "email":"the.road.runner@acme.org",
            "message":"Beep! Beep!"
        },
        "metadata":{
            "url":"https://cdn.chatpirate.com/preview.html?l=1963030101"
        },
        "read":false,
        "createdAt":"2016-05-06T07:26:24+0000"
    }
}

Update read status

HTTP Request

$ curl -X PATCH \
    'https://app.chatpirate.com/api/v1/ticket/1' \
    -u 'wille.e.coyote@acme.org:qwerty123'

PATCH https://app.chatpirate.com/api/v1/ticket/{id}

Example response

{
    "message":"Ticket successfully updated",
    "data":{
        "ticketId":1,
        "companyId":1963030101,
        "visitor":{
            "email":"the.road.runner@acme.org",
            "message":"Beep! Beep!"
        },
        "metadata":{
          "url":"https://cdn.chatpirate.com/preview.html?l=1963030101"
        },
        "read":true,
        "createdAt":"2016-05-06T07:26:24+0000",
        "updatedAt":"2016-05-06T07:57:16+0000"
    }
}

Remove ticket(s)

HTTP Request

Remove single ticket

$ curl -X DELETE \
    'https://app.chatpirate.com/api/v1/ticket/1' \
    -u 'wille.e.coyote@acme.org:qwerty123'

Remove list of tickets

$ curl -X DELETE \
    'https://app.chatpirate.com/api/v1/ticket' \
    -u 'wille.e.coyote@acme.org:qwerty123' \
    -H 'Content-Type: application/json' \
    -d '{ "tickets": [1, 2] }'

DELETE https://app.chatpirate.com/api/v1/ticket/{id}

Example response

{
    "message":"Ticket deleted"
}

Request Parameters

Parameter Required Type Description
id no Number Ticket {id}
tickets no Array.<Number> List of tickets {ids}

List of forwarded emails

HTTP Request

$ curl 'https://app.chatpirate.com/api/v1/ticket/emails/0' \
    -u 'wille.e.coyote@acme.org:qwerty123'

GET https://app.chatpirate.com/api/v1/ticket/emails/{sectionId}

Example response

{
    "message":"Success",
    "data":[
        "wille.e.coyote@acme.org",
        "the.road.runner@acme.org"
    ]
}

Update list of forwarded emails

HTTP Request

$ curl -X PATCH \
      'https://app.chatpirate.com/api/v1/ticket/emails/0' \
      -u 'wille.e.coyote@acme.org:qwerty123' \
      -H 'Content-Type: application/json' \
      -d '{
            "emails": [
                "wille.e.coyote@acme.org",
                "the.road.runner@acme.org"
            ]
      }'

PATCH https://app.chatpirate.com/api/v1/ticket/emails/{sectionId}

Example response

{
    "message":"Ticket emails successfully updated",
    "data":[
        "wille.e.coyote@acme.org",
        "the.road.runner@acme.org"
    ]
}

Request Parameters

Parameter Required Type Description
emails no Array.<Email> List of emails

Unread notifications

Object of unreaded messages and tickets for current (logged) operator.

HTTP Request

$ curl 'https://app.chatpirate.com/api/v1/notification/badges' \
    -u 'wille.e.coyote@acme.org:qwerty123'

GET https://app.chatpirate.com/api/v1/notification/badges

Example response

{
    "message":"Success",
    "data":{
        "unreadMessages":0,
        "unreadTickets":0
    }
}

Traffic

List all visitors

Returns list of visitors currently browsing pages where ChatPirate is installed.

HTTP Request

$ curl 'https://app.chatpirate.com/api/v1/traffic' \
    -u 'wille.e.coyote@acme.org:qwerty123'

GET https://app.chatpirate.com/api/v1/traffic

Example response

{
    "message":"Success",
    "data":[
        {
            // visitor object
        }
    ]
}

Get a single visitor details

HTTP Request

$ curl 'https://app.chatpirate.com/api/v1/traffic/61662c73-6bff-429d-a5d4-e44db1d477f2' \
    -u 'wille.e.coyote@acme.org:qwerty123'

GET https://app.chatpirate.com/api/v1/traffic/{sessionId}

Example response

{
    "message":"Success",
    "data":{
        "companyId":1963030101,
        "sessionId":"61662c73-6bff-429d-a5d4-e44db1d477f2",
        "banned":false,
        "firstVisit":"2016-05-05T14:11:26.294Z",
        "lastVisit":"2016-05-06T07:26:07.197Z",
        "totalVisits":2,
        "totalChats":1,
        "data":{
           "name":"The Road Runner",
           "email":"the.road.runner@acme.org"
        },
        "visit":{
           "date":"2016-05-06T07:26:07.197Z",
           "host":"localhost",
           "ip":"192.168.1.1",
           "referrer":"https://google.com",
           "userAgent":"Mozilla/5.0 (X11; Linux x86_64) Chrome/50.0.2661.94",
           "language":"en",
           "timezone":"America/Los_Angeles",
           "invitation":{
               "invited":false,
               "type":false,
               "name":false,
               "message":false,
               "id":false,
               "operator":false
           },
           "location":{
               "city":"Mountain View",
               "countryName":"United States",
               "countryCode":"US",
               "region":"California"
           },
           "browsing":[
               {
                   "pageUrl":"https://acme.org/",
                   "pagePath":"/",
                   "pageTitle":"ACME Corporation",
                   "startTime":"2016-05-06T07:26:07.197Z",
                   "leaveTime":"2016-05-06T07:26:20.197Z"
               }
           ]
        }
    }
}

Settings

List all sections settings

HTTP Request

$ curl 'https://app.chatpirate.com/api/v1/company/settings' \
    -u 'wille.e.coyote@acme.org:qwerty123'

GET https://app.chatpirate.com/api/v1//companysettings

Example response

{
    "message":"Success",
    "data": [
        {
            // settings object
        }
    ]
}

Get a single section settings

HTTP Request

$ curl 'https://app.chatpirate.com/api/v1/company/settings/0' \
    -u 'wille.e.coyote@acme.org:qwerty123'

GET https://app.chatpirate.com/api/v1//company/settings/{section}

Example response

{
    "message":"Success",
    "data": {
        "section":0,
        "language":"en",
        "logo":false,
        "chatStyle":{
            // chatStyle object
        },
        "locales":{
            // locales object
        },
        "catcher":{
            // catcher object
        },
        "autoInvitations":[
            {
                // invitation object
            }
        ],
        "preChatSurvey":{
            "enabled":true,
            "fields":[
                {
                    // survey field object
                }
            ]
        },
        "offlineSurvey":{
            "enabled":true,
            "fields":[
                {
                    // survey field object
                }
            ]
        },
        "ticketEmails":[
            "wille.e.coyote@acme.org",
            "the.road.runner@acme.org"
        ]
    }
}

Update settings

HTTP Request

$ curl -X PATCH \
    'https://app.chatpirate.com/api/v1/company/settings/0' \
    -H 'Content-Type: application/json' \
    -u 'wille.e.coyote@acme.org:qwerty123' \
    -d '{ "language": "se" }'

PATCH https://app.chatpirate.com/api/v1//company/settings/{section}

Example response

Request Parameters

Parameter Required Type Description
language no String Abridged language name, standard: ISO_3166-1 alfa-2

Allowed values: en, pl, de, ru, fr, se, nl, no, es, it
chatStyle no Object Appearance of chat
locales no Object Translations
catcher no Object Eye-catcher visible graphic to draw visitors’ attention
preChatSurvey no Object Form before conversation
offlineSurvey no Object Leave a message form

Properties of chatStyle object

{
    "chatStyle": {
        "theme":"standard",
        "direction":{
            "right":"20px",
            "bottom":"0px"
        },
        "color":{
            "plugin":"#496492",
            "button":"#46A0D8"
        },
        "customCss":false
    }
}
Parameter Type Description
theme String Style name

Allowed values: standard
color.plugin String Plugin color in HEX
color.button String Buttoncolor in HEX
direction.left String Chat horizontal position

If right atrribute exists You can’t add left atrribute

Size range: between:3,6
direction.right String Chat horizontal position

If left atrribute exists You can’t add right atrribute

Size range: between:3,6
direction.top String Chat vertical position

If bottom atrribute exists You can’t add top atrribute

Size range: between:3,6
direction.bottom String Chat vertical position

If top atrribute exists You can’t add bottom atrribute

Size range: between:3,6

Properties of locales object

Example

{
    "locales":{
        "chat_button_online_title":"Chat with us!",
        "chat_window_welcome_message":"Welcome, how can I help you?",
        "chat_window_online_title":"Welcome to ChatPirate!",
        "chat_button_offline_title":"Leave us a message"
    }
}
Parameter Type Description
key String Possible keys: chat_window_online_title, chat_window_welcome_message, chat_button_offline_title, chat_button_online_title
value String Translation

Properties of catcher object

Example

{
    "catcher":{
        "enabled":true,
        "url":false,
        "css":{
            "width":"230px",
            "height":"250px"
        }
    }
}
Parameter Type Description
enabled Boolean Turn on/off
url Url Url address
css.width String Catcher width in pixels

Size range: between:3,6
css.height String Catcher height in pixels

Size range: between:3,6
css.direction String Value based on plugin position in pixels

Size range: between:3,6
css.bottom String Catcher horizontal position in pixels, based on chatStyle.direction

Size range: between:3,6

Properties of survey field object

Example preChatSurvey

{
    "fields":[
        {
            "id":"aa",
            "label":"Welcome to ChatPirate! Please fill in the form below before starting the chat.",
            "type":"text",
            "element":"paragraph",
            "require":false
        },
        {
            "id":"bb",
            "label":"Name",
            "type":"name",
            "element":"input",
            "require":true
        },
        {
            "id":"cc",
            "label":"E-mail",
            "type":"email",
            "element":"input",
            "require":true
        }
    ]
}
Parameter Type Description
id String Unique field id

Size range: between:2:8
label String Text or translation key

Size range: when type paragraph - between:2:500, rest types - between:2,30
type String Field type

Allowed values: email, name, telephone, text, custom
element String Element type

Allowed values: paragraph, input, textarea
require Boolean Mark field as required

HTTP Request

$ curl -X PATCH \
    'https://app.chatpirate.com/api/v1/company/settings/0/deleteLogo' \
    -u 'wille.e.coyote@acme.org:qwerty123'

PATCH https://app.chatpirate.com/api/v1//company/settings/{section}/deleteLogo

Example response

{
    "message":"Logo has been deleted correctly",
    "data":{
        // settings object
    }
}

Automatic invitations

Get a single invitation

HTTP Request

$ curl 'https://app.chatpirate.com/api/v1/automatic-invitations/0/p-alnyon-rl' \
    -u 'wille.e.coyote@acme.org:qwerty123'

GET https://app.chatpirate.com/api/v1/automatic-invitations/{section}/{id}

Example response

{
    "data":{
        "id":"p-alnyon-rl",
        "enabled":false,
        "message":"Welcome again! Can I help You?",
        "rules":[
            {
                "type":"totalVisits",
                "operator":"equals",
                "value":3
            }
        ]
    }
}

Update invitation

HTTP Request

$ curl -X PATCH \
    'https://app.chatpirate.com/api/v1/automatic-invitations/0/p-alnyon-rl' \
    -u 'wille.e.coyote@acme.org:qwerty123' \
    -H 'Content-Type: application/json' \
    -d '{
        "enabled": true,
        "message": "Welcome, how can I help you?",
        "rules": [
            {
                "type": "page",
                "operator": "contains",
                "value": "/checkout"
            }
        ]
    }'

PATCH https://app.chatpirate.com/api/v1/automatic-invitations/{section}/{id}

Example response

{
    "message":"Automatic invitations successfully updated",
    "data":{
        "id":"p-alnyon-rl",
        "enabled":true,
        "message":"Welcome, how can I help you?",
        "rules":[
            {
                "type":"page",
                "operator":"contains",
                "value":"/checkout"
            }
        ]
    }
}

Request Parameters

Parameter Type Description
enabled Boolean Turn on/off
message String Message text

Size range: between:2,200
rules Array

Properties of rule object

Parameter Type Description
type String page - the address of the page
pageViews - number of visits totalVisits - the number of visits (one visit = one session, one session per day)
referrer - the address of the page from which the user was redirected
totalChats - the total number of chats
firstVisit - Time on the website
lastVisit - Time on the current page
location - geographical location
params - custom parameter
operator String equals - equals value (used with numbers and strings)
doesnt_equal - does not equal value (used with numbers and strings)
greater_than - greater than value (used with numbers)
greater_or_equal - greater than or equal value (used with numbers)
lower_than - lower than value (used with numbers)
lower_or_equal - lower or equal value (used with numbers)
contains - contains value (used with numbers and strings)
doesnt_contain - does not contain value (used with numbers and strings)
value String Value of rule

Remove invitation

HTTP Request

$ curl -X DELETE \
    'https://app.chatpirate.com/api/v1/automatic-invitations/0/p-alnyon-rl' \
    -u 'wille.e.coyote@acme.org:qwerty123'

DELETE https://app.chatpirate.com/api/v1/automatic-invitations/{section}/{id}

Example response

{
    "message":"Automatic invitations successfully deleted"
}

Webhooks

List of configured webhooks

HTTP Request

$ curl 'https://app.chatpirate.com/api/v1/webhook' \
    -u 'wille.e.coyote@acme.org:qwerty123'

GET https://app.chatpirate.com/api/v1/webhook

Example response

{
    "message":"Success",
    "data":[
        {
            "id": "56ceb1f6ac01d09c65c271e2",
            "companyId": 1963030101,
            "event": "offlineSurvey",
            "template": "basic",
            "createdByUser": true,
            "url": "https://user:password@acme.org/webhook"
        }
    ]
}

Create a new webhook

Webhooks are always send as POST method, with Content-Type of application/json.

HTTP Request

$ curl -X POST \
    'https://app.chatpirate.com/api/v1/webhook' \
    -u 'wille.e.coyote@acme.org:qwerty123' \
    -H 'Content-Type: application/json' \
    -d '{
        "event": "offlineSurvey",
        "template": "basic",
        "url": "https://user:password@acme.org/webhook"
    }'

POST https://app.chatpirate.com/api/v1/webhook

Example response

{
    "message":"Webhook successfully created",
    "data":{
        "id": "56ceb1f6ac01d09c65c271e2",
        "companyId": 1963030101,
        "event": "offlineSurvey",
        "template": "basic",
        "createdByUser": true,
        "url": "https://user:password@acme.org/webhook"
    }
}

Request Parameters

Parameter Type Description
event String Allowed values: offlineSurvey
template String Allowed values: basic, slack
url String Url address

Delete a webhook

HTTP Request

$ curl -X DELETE \
    'https://app.chatpirate.com/api/v1/webhook/56ceb1f6ac01d09c65c271e2' \
    -u 'wille.e.coyote@acme.org:qwerty123'

DELETE https://app.chatpirate.com/api/v1/webhook/{id}

Example response

{
    "message":"Webhook deleted"
}

Troubleshooting

If the status code in the payload response is not in the 200-299 range or if the request times out after 10 seconds, We’ll automatically resends the response up to five times, with twenty minutes between each attempt. The last HTTP error response status message (reason phrase) is logged in webhook body, which is cleared after first successfully attempt.

Example webhook with error property

{
    "id": "56ceb1f6ac01d09c65c271e2",
    "companyId": 1963030101,
    "event": "offlineSurvey",
    "template": "basic",
    "createdByUser": true,
    "url": "https://user:password@acme.org/webhook",
    "error": {
        "count": 5,
        "message": "Internal Server Error"
    }
}

JavaScript API

The ChatPirate JavaScript API provides a way for developers to modify the default behavior of the chat widget on web pages.

The JavaScript tracking snippet

<script type="text/javascript">
    var __cp = {};
    __cp.license = 1963030101;

    (function(){
        var s = document.createElement('script'); s.type = 'text/javascript'; s.async = true;
        s.src = 'https://cdn.chatpirate.com/plugin.js';
        var sc = document.getElementsByTagName('script')[0]; sc.parentNode.insertBefore(s, sc);
    })();
</script>

Alternative tracking snippet

<script type="text/javascript">
    var __cp = {};
    __cp.license = 1963030101;
</script>
<script async src="https://cdn.chatpirate.com/plugin.js"></script>

Adding the following code to your site’s templates is the easiest way to get started using ChatPirate. The code should be added before the closing </body> tag, and the number 1963030101 should be replaced with your license number.

Working with scopes

<script type="text/javascript">
    window.__cp = window.__cp || {};

    window.__cp.license = 1963030101;

    (function(){
        var s = document.createElement('script'); s.type = 'text/javascript'; s.async = true;
        s.src = 'https://cdn.chatpirate.com/plugin.js';
        var sc = document.getElementsByTagName('script')[0]; sc.parentNode.insertBefore(s, sc);
    })();
</script>

Sometimes you might want to embed ChatPirate code snippet inside your own code, in different than main scope. To workaround that you have to set __cp variable as window property.

Tracking code options

    var __cp = {};

    /**
     * ChatPirate license number
     *
     * @type {Number}
     */
    __cp.license = 1963030101;

    /**
     * Section number
     *
     * @type {Number}
     * @default
     */
    __cp.section = 0;

    /**
     * The chat widget language
     *
     * @type {String}
     * @default
     */
    __cp.language = 'en';

    /**
     * Custom variables
     *
     * @type {Array.<Object>}
     */
    __cp.params = [
        {
            name: 'acme.org login',
            value: 'The Road Runner'
        }
    ];

    (function(){
        var s = document.createElement('script'); s.type = 'text/javascript'; s.async = true;
        s.src = 'https://cdn.chatpirate.com/plugin.js';
        var sc = document.getElementsByTagName('script')[0]; sc.parentNode.insertBefore(s, sc);
    })();

Events

The ChatPirate JavaScript API is loaded asynchronously, which limits usage of API calls to events scope.

onBeforeLoad

var CP_API = CP_API || {};

/**
 * @callback onBeforeLoad
 */
CP_API.onBeforeLoad = function(){

    // ..

};

Callback function invoked when widget code is loaded but chat window is not rendered yet. Useful to override some default appearance and behavior, like disable chat button.

onLoad

var CP_API = CP_API || {};

/**
 * @callback onLoad
 */
CP_API.onLoad = function(){

    // ..

};

Callback function invoked when widget code is loaded and chat window is rendered.

onChatStart

var CP_API = CP_API || {};

/**
 * @callback onChatStart
 *
 * @param operator {Object}
 * @param operator.id {Number}
 * @param operator.name {String}
 * @param operator.jobTitle {String}
 * @param operator.avatar {String}
 */
CP_API.onChatStart = function(operator){

    // ..

};

Callback function invoked when the chat starts.

onChatFinished

var CP_API = CP_API || {};

/**
 * @callback onChatFinished
 */
CP_API.onChatFinished = function(){

    // ..

};

Callback function invoked when the chat ends.

onChatMessage

var CP_API = CP_API || {};

/**
 * @callback onChatMessage
 *
 * @param message {Object}
 * @param message.authorType {String} user or operator
 * @param message.message {String} the content of message
 * @param message.name {String} the name of the author that sends the message
 * @param message.time {Date}
 */
CP_API.onChatMessage = function(message){

    // ..

};

Callback function invoked when the message was send by user or operator.

onCreateOfflineMessage

var CP_API = CP_API || {};

/**
 * @callback onCreateOfflineMessage
 *
 * @param ticket {Object} the ticket object
 */
CP_API.onCreateOfflineMessage = function(ticket){

    // ..

};

Callback function invoked when offline survey (ticket) has been created.

onChatWindowOpen

var CP_API = CP_API || {};

/**
 * @callback onChatWindowOpen
 */
CP_API.onChatWindowOpen = function(){

    // ..

};

Callback function invoked when the chat window is opened.

onChatWindowClose

var CP_API = CP_API || {};

/**
 * @callback onChatWindowClose
 */
CP_API.onChatWindowClose = function(){

    // ..

};

Callback function invoked when the chat window is closed.

onChatWindowMinimize

var CP_API = CP_API || {};

/**
 * @callback onChatWindowMinimize
 */
CP_API.onChatWindowMinimize = function(){

    // ..

};

Callback function invoked when the chat window is minimized.

onChatInvitation

var CP_API = CP_API || {};

/**
 * @callback onChatInvitation
 *
 * @param invitation {Object}
 * @param invitation.enabled {Boolean}
 * @param invitation.message {String}
 * @param invitation.rules {Array}
 * @param invitation.rules[].type {String}
 * @param invitation.rules[].operator {String}
 * @param invitation.rules[].value {String}
 */
CP_API.onChatInvitation = function(invitation){

    // ..

};

Callback function invoked when the visitor is invited.

onChatCatcherClose

var CP_API = CP_API || {};

/**
 * @callback onChatCatcherClose
 */
CP_API.onChatCatcherClose = function(){

    // ..

};

Callback function invoked when the chat catcher is closed.

onAvailabilityStateChange

var CP_API = CP_API || {};

/**
 * @callback onAvailabilityStateChange
 *
 * @param state {String} online or offline
 */
CP_API.onAvailabilityStateChange = function(state){

    // ..

};

Callback function invoked when the chat state is changed.

Methods

openChatWindow

var CP_API = CP_API || {};

CP_API.onLoad = function(){

    CP_API.openChatWindow();

};

Open the chat window, should be used only inside CP_API.onLoad callback.

closeChatWindow

var CP_API = CP_API || {};

CP_API.onLoad = function(){

    CP_API.closeChatWindow();

};

Close the chat window, should be used only inside CP_API.onLoad callback.

minimizeChatWindow

var CP_API = CP_API || {};

CP_API.onLoad = function(){

    CP_API.minimizeChatWindow();

};

Minimizes the chat window, should be used only inside CP_API.onLoad callback.

disableChatButton

var CP_API = CP_API || {};

CP_API.onBeforeLoad = function(){

    CP_API.disableChatButton();

};

Hide the chat button and the chat catcher, before the chat window is rendered, should be used only inside CP_API.onBeforeLoad callback.

hideChatButton

var CP_API = CP_API || {};

CP_API.onLoad = function(){

    CP_API.hideChatButton();

};

Hide the chat button and the chat catcher, after the chat window is rendered, should be used only inside CP_API.onLoad callback.

startChatInvitation

var CP_API = CP_API || {};

CP_API.onLoad = function(){


    CP_API.startChatInvitation('p-alnyon-rl');

};

Starts the chat invitation, false is returned when provided {invitationId} is incorrect. Should be used only inside CP_API.onLoad callback.

disableChatInvitation

var CP_API = CP_API || {};

CP_API.onBeforeLoad = function(){

    CP_API.disableChatInvitation();

};

Disable the chat invitation before the chat window is rendered. Should be used only inside CP_API.onBeforeLoad callback.

hideChatCatcher

var CP_API = CP_API || {};

CP_API.onLoad = function(){

    CP_API.hideChatCatcher();

};

Hide the chat catcher, after the chat window is rendered, should be used only inside CP_API.onLoad callback.

disableChatCatcher

var CP_API = CP_API || {};

CP_API.onBeforeLoad = function(){

    CP_API.disableChatCatcher();

};

Disable the chat invitation before the chat window is rendered. Should be used only inside CP_API.onBeforeLoad callback.

isChatWindowOpened

var CP_API = CP_API || {};

CP_API.onLoad = function(){

    console.log(CP_API.isChatWindowOpened());

};

Returns true if the chat window is opened, otherwise false. Undefined is returned when used before the chat window is loaded. Should be used only inside CP_API.onLoad callback.

isChatWindowClosed

var CP_API = CP_API || {};

CP_API.onLoad = function(){

    console.log(CP_API.isChatWindowOpened());

};

Returns true if the chat window is closed, otherwise true. Undefined is returned when used before the chat window is loaded. Should be used only inside CP_API.onLoad callback.

getVisitorID

var CP_API = CP_API || {};

CP_API.onLoad = function(){

    console.log(CP_API.getVisitorID());

};

Returns visitor unique ID. Undefined is returned when used before the chat window is loaded. Should be used only inside CP_API.onLoad callback.

getVisitorLastVisitTime

var CP_API = CP_API || {};

CP_API.onLoad = function(){

    console.log(CP_API.getVisitorLastVisitTime());

};

Returns the Date object with date of last the visitor visit. Undefined is returned when used before the chat window is loaded. Should be used only inside CP_API.onLoad callback.

getVisitorTotalVisitsNumber

var CP_API = CP_API || {};

CP_API.onLoad = function(){

    console.log(CP_API.getVisitorTotalVisitsNumber());

};

Returns the number of the visitor visits. Undefined is returned when used before the chat window is loaded. Should be used only inside CP_API.onLoad callback.

getChatId

var CP_API = CP_API || {};

CP_API.onLoad = function(){

    console.log(CP_API.getChatId());

};

Returns the chat ID if the visitor is chatting. Undefined is returned when used before the chat window is loaded. Should be used only inside CP_API.onLoad callback.

isVisitorChatting

var CP_API = CP_API || {};

CP_API.onLoad = function(){

    console.log(CP_API.isVisitorChatting());

};

Returns true if the visitor is chatting, otherwise false. Undefined is returned when used before the chat window is loaded. Should be used only inside CP_API.onLoad callback.

isVisitorInvited

var CP_API = CP_API || {};

CP_API.onLoad = function(){

    console.log(CP_API.isVisitorInvited());

};

Returns true if the visitor is invited, otherwise false. Undefined is returned when used before the chat window is loaded. Should be used only inside CP_API.onLoad callback.

isOperatorAvailable

var CP_API = CP_API || {};

CP_API.onLoad = function(){

    console.log(CP_API.isOperatorAvailable());

};

Returns availability status. Undefined is returned when used before the chat window is loaded. Should be used only inside CP_API.onLoad callback.

updateVisitorParams

var CP_API = CP_API || {};

CP_API.onLoad = function(){

    /**
     * @typedef {Object} visitorParam
     * @property {String} name
     * @property {String} value
     */

    /**
     * @typedef {Array.<visitorParam>} visitorParams
     */
    var params = [
        {
            name: 'acme.org login',
            value: 'The Road Runner'
        }
    ];

    /**
     * @param {visitorParams} params
     * @param {function|undefined=} callback
     *
     * @returns {undefined}
     */
    CP_API.updateVisitorParams(params, function(){

        // ..

    });

};

Update the visitor params. Should be used only inside CP_API.onLoad callback.

Examples

Hiding the widget when offline

var CP_API = CP_API || {};

// hide the chat button on state change and on load, when there are no operators available
CP_API.onLoad = CP_API.onAvailabilityStateChange = function(){

    if(!CP_API.isOperatorAvailable())
    {

        CP_API.hideChatButton();

    }

};

Custom-looking chat button

<a href="#" class="my-chat-button">CHAT WITH US</a>

<script type="text/javascript">
    var CP_API = CP_API || {};

    // hide the chat button
    CP_API.onBeforeLoad = function(){

        CP_API.hideChatButton();

    };

    // bind CP_API.openChatWindow to your custom button
    CP_API.onLoad = function(){

        // vanilla javascript example
        document
            .querySelector('.my-chat-button')
            .addEventListener('click', CP_API.openChatWindow);

        // jQuery example
        $('.my-chat-button').on('click', CP_API.openChatWindow);

    };
</script>

Integration with Google Analytics

Example for ga.js (legacy)

var CP_API = CP_API || {};

CP_API.onChatStart = function(operator){

    _gaq.push(['_trackEvent', 'ChatPirate', 'Chat', operator.name]);

};

Example for analytics.js (universal analytics)

var CP_API = CP_API || {};

CP_API.onChatStart = function(operator){

    ga('send', 'event', 'ChatPirate', 'Chat', operator.name);

};