User/Contact API

Use these sets of API if you wish to sync your user or contact into OneTalk's system.

Request Auth Ticket

Request auth ticket for Live Chat on behalf of the specified user/contact, passing along the user's data to be saved to contacts. The auth ticket can be used to request an access token for Live Chat. An auth ticket is valid for 1 hour before it expires.
POST
https://onetalk-api.taptalk.io/v1/user/request_auth_ticket
Field
Type
Description
API-Key
String
API key for accessing the API.

Request

Field
Type
Description
customerUserID
String
User ID from customer's server.
Size Range 1..100
fullName
String
The user's full name.
Size Range 1..250
alias (optional)
String
The user's alias.
Size Range 1..100
email (optional)
String
The user's email address.
Size Range 1..250
phone (optional)
String
The user's phone, must start with country code.
Size Range 1..20
photoURL (optional)
String
The user's picture image URL
Request Example
{
"customerUserID": "company:123",
"fullName": "John Doe",
"alias": "",
"email": "[email protected]",
"phone": "6281234567890",
"photoURL": "http://www.example.com/photo/john_doe.jpg"
}

Success 200

Field
Type
Description
success
boolean
If successful.
message
string
The message.
userID
string
The user ID from OneTalk.
ticket
string
The auth ticket to request an access token.
Success Response
{
"status": 200,
"error": {
"code": "",
"message": "",
"field": ""
},
"data": {
"success": true,
"message": "Contact updated successfully",
"userID": "354c63e1-2485-4380-b307-4f2ea1ff69d0",
"ticket": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
}

Error 4xx

Name
Description
ParamValidationFailed
The parameter validation failed.
HeaderValidationFailed
The request header validation failed.
TierNotSelected
The organization has not selected a tier.
ParamValidationFailed
HeaderValidationFailed
TierNotSelected
{
"status": 400,
"error": {
"code": "40002",
"message": "Customer user ID is required",
"field": "customerUserID"
},
"data": {}
}
{
"status": 400,
"error": {
"code": "40001",
"message": "Request headers are required (API-Key)",
"field": ""
},
"data": {}
}
{
"status": 499,
"error": {
"code": "49900",
"message": "Please select a tier",
"field": ""
},
"data": {}
}

Sync User Contact

Sync a user from the customer's server to OneTalk contacts.
The sync process will check for existing contacts using all the following keys:
  • customerUserID (required)
  • phone (optional)
If no contact is found, a new contact will be created. If exactly one contact is found using the sync keys, the contact will be updated. If more than one contacts are found, the sync will be rejected because duplicate keys are not allowed.
Customer user ID can't be changed for existing contacts. So, if the existing contact is already tied to a different customer user ID, the sync will be rejected. However, if the existing contact is not tied to any customer user ID yet, it will be updated to the specified customerUserID.
POST
https://onetalk-api.taptalk.io/api/integration/v1/user/sync_contact

Header

Field
Description
API-Key
API key for accessing the API.
Content-Type (optional)
Content type of the request body.
User-Agent (optional)
The user agent of the client accessing the API.

Request

Field
Type
Description
customerUserID
String
UserID from customer's server. Size Range 1..100
fullName
String
The user's full name. Size Range 1..100
alias
String
The user's alias. Size Range 1..100
email
String
The user's email address. Size Range 1..100
phone
String
The user's phone, must start with country code. Size Range 1..100
photoURL
String
The user's picture image URL.
Request Example
{
"customerUserID": "company:123",
"fullName": "John Doe",
"alias": "",
"email": "[email protected]",
"phone": "6281234567890",
"photoURL": "http://www.example.com/photo/john_doe.jpg"
}

Success 200

Field
Type
Description
success
boolean
If saved successfully.
message
string
The message.
userID
string
The user ID from OneTalk.
Success Response
{
"status": 200,
"error": {
"code": "",
"message": "",
"field": ""
},
"data": {
"success": true,
"message": "Contact updated successfully",
"userID": "354c63e1-2485-4380-b307-4f2ea1ff69d0"
}
}

Error 4xx

Name
Description
ParamValidationFailed
The parameter validation failed.
HeaderValidationFailed
The request header validation failed.
TierNotSelected
The organization has not selected the tier.
ParamValidationFailed
HeaderValidationFailed
TierNotSelected
{
"status": 400,
"error": {
"code": "40002",
"message": "Customer user ID is required",
"field": "customerUserID"
},
"data": {}
}
{
"status": 400,
"error": {
"code": "40001",
"message": "Request headers are required (API-Key)",
"field": ""
},
"data": {}
}
{
"status": 499,
"error": {
"code": "49900",
"message": "Please select a tier",
"field": ""
},
"data": {}
}