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/api/integration/v1/user/request_auth_ticket

Header

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": "[e-mail]",
  "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

{
  "status": 400,
  "error": {
    "code": "40002",
    "message": "Customer user ID is required",
    "field": "customerUserID"
  },
  "data": {}
}

HeaderValidationFailed

{
  "status": 400,
  "error": {
    "code": "40001",
    "message": "Request headers are required (API-Key)",
    "field": ""
  },
  "data": {}
}

TierNotSelected

{
  "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": "[e-mail]",
    "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

{
  "status": 400,
  "error": {
    "code": "40002",
    "message": "Customer user ID is required",
    "field": "customerUserID"
  },
  "data": {}
}

HeaderValidationFailed

{
  "status": 400,
  "error": {
    "code": "40001",
    "message": "Request headers are required (API-Key)",
    "field": ""
  },
  "data": {}
}

TierNotSelected

{
  "status": 499,
  "error": {
    "code": "49900",
    "message": "Please select a tier",
    "field": ""
  },
  "data": {}
}