# User/Contact API

### 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.

{% tabs %}
{% tab title="POST" %}

```
https://onetalk-api.taptalk.io/api/integration/v1/user/request_auth_ticket
```

{% endtab %}
{% endtabs %}

### Header

| Field   | Type   | Description                    |
| ------- | ------ | ------------------------------ |
| API-Key | String | API key for accessing the API. |

### Request

| Field               | Type   | Description                                                                                |
| ------------------- | ------ | ------------------------------------------------------------------------------------------ |
| customerUserID      | String | <p>User ID from customer's server.</p><p>Size Range <code>1..100</code></p>                |
| fullName            | String | <p>The user's full name.</p><p>Size Range <code>1..250</code></p>                          |
| alias (optional)    | String | <p>The user's alias.</p><p>Size Range <code>1..100</code></p>                              |
| email (optional)    | String | <p>The user's email address.</p><p>Size Range <code>1..250</code></p>                      |
| phone (optional)    | String | <p>The user's phone, must start with country code.</p><p>Size Range <code>1..20</code></p> |
| photoURL (optional) | String | The user's picture image URL                                                               |

{% tabs %}
{% tab title="Request Example" %}

```json
{
  "customerUserID": "company:123",
  "fullName": "John Doe",
  "alias": "",
  "email": "john_doe@example.com",
  "phone": "6281234567890",
  "photoURL": "http://www.example.com/photo/john_doe.jpg"
}
```

{% endtab %}
{% endtabs %}

### 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. |

{% tabs %}
{% tab title="Success Response" %}

```json
{
  "status": 200,
  "error": {
    "code": "",
    "message": "",
    "field": ""
  },
  "data": {
    "success": true,
    "message": "Contact updated successfully",
    "userID": "354c63e1-2485-4380-b307-4f2ea1ff69d0",
    "ticket": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}
```

{% endtab %}
{% endtabs %}

### Error 4xx

| Name                   | Description                               |
| ---------------------- | ----------------------------------------- |
| ParamValidationFailed  | The parameter validation failed.          |
| HeaderValidationFailed | The request header validation failed.     |
| TierNotSelected        | The organization has not selected a tier. |

{% tabs %}
{% tab title="ParamValidationFailed" %}

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

{% endtab %}

{% tab title="HeaderValidationFailed" %}

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

{% endtab %}

{% tab title="TierNotSelected" %}

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

{% endtab %}
{% endtabs %}

### 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`.

{% tabs %}
{% tab title="POST" %}

```
https://onetalk-api.taptalk.io/api/integration/v1/user/sync_contact
```

{% endtab %}
{% endtabs %}

### 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 | <p>UserID from customer's server.<br>Size Range <code>1..100</code></p>                  |
| fullName       | String | <p>The user's full name.<br>Size Range <code>1..100</code></p>                           |
| alias          | String | <p>The user's alias.<br>Size Range <code>1..100</code></p>                               |
| email          | String | <p>The user's email address.<br>Size Range <code>1..100</code></p>                       |
| phone          | String | <p>The user's phone, must start with country code.<br>Size Range <code>1..100</code></p> |
| photoURL       | String | The user's picture image URL.                                                            |

{% tabs %}
{% tab title="Request Example" %}

```go
{
    "customerUserID": "company:123",
    "fullName": "John Doe",
    "alias": "",
    "email": "john_doe@example.com",
    "phone": "6281234567890",
    "photoURL": "http://www.example.com/photo/john_doe.jpg"
}
```

{% endtab %}
{% endtabs %}

### Success 200

| Field   | Type    | Description               |
| ------- | ------- | ------------------------- |
| success | boolean | If saved successfully.    |
| message | string  | The message.              |
| userID  | string  | The user ID from OneTalk. |

{% tabs %}
{% tab title="Success Response" %}

```json
{
  "status": 200,
  "error": {
    "code": "",
    "message": "",
    "field": ""
  },
  "data": {
    "success": true,
    "message": "Contact updated successfully",
    "userID": "354c63e1-2485-4380-b307-4f2ea1ff69d0"
  }
}
```

{% endtab %}
{% endtabs %}

### Error 4xx

| Name                   | Description                                 |
| ---------------------- | ------------------------------------------- |
| ParamValidationFailed  | The parameter validation failed.            |
| HeaderValidationFailed | The request header validation failed.       |
| TierNotSelected        | The organization has not selected the tier. |

{% tabs %}
{% tab title="ParamValidationFailed" %}

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

{% endtab %}

{% tab title="HeaderValidationFailed" %}

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

{% endtab %}

{% tab title="TierNotSelected" %}

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

{% endtab %}
{% endtabs %}