> ## Documentation Index
> Fetch the complete documentation index at: https://help.emotive.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Set up a Custom Helpdesk Integration

> Developer instructions to configure a custom helpdesk integration with Emotive.

You can find developer documentation [here](https://api-gw.emotiveapp.co/helpdesk/ui/#/default/controllers.connections.post).

## Required Configuration

### Brand Token

* Get ticket system ID from this endpoint:

[**https://api-gw.emotiveapp.co/helpdesk/ui/#/default/controllers.ticket\_systems.get**](https://api-gw.emotiveapp.co/helpdesk/ui/#/default/controllers.ticket_systems.get)

* Create Brand Token by sending post request to this endpoint:

[**https://api-gw.emotiveapp.co/helpdesk/ui/#/default/controllers.connections.post**](https://api-gw.emotiveapp.co/helpdesk/ui/#/default/controllers.connections.post)

### Generate Helpdesk Brand Token

* Get system type id

```
GET /ticket_systems
Headers:
  Authorization: bearer {emotive JWT}
```

* Generate a Brand Token

```
POST /connections/config
Headers:
  Authorization: bearer {emotive JWT}

Payload:
{
    "auth_type": "api_token",
    "status": "active",
    "ticket_system_type_id": 0 # < get this ID from the system type list endpoint
}
```

### Token usage

A token is used to authenticate requests to the helpdesk. Each brand may have only 1 active token.

You can get a token on the Emotive dashboard page (UI is in progress, use above mentioned API to get `brand_token` ).

Once a token is created, use it for all requests to Helpdesk API. Pass it as an `X-Api-Key` header value:

```
Headers:
  X-Api-Key: {brand_token}
```

## Brand webhooks

Brand should create a webhook endpoint that the helpdesk will call. These webhooks would be called for the following events:

* Ticket creation
* Note addition (Once a ticket for brand user is created - all next ticket events will be passed as ticket notes.)

*SMS Subscriber can only have 1 active ticket at time.*

### Define webhooks

Webhooks will be used to notify the brand’s platform about new tickets or ticket messages.

A brand must provide 2 endpoints:

* **Ticket creation** - once a ticket is created in the helpdesk, this endpoint will be notified
* **Ticket update** - notification on a message from the user (for an existing ticket)

Example:

```
POST /webhooks/config
Headers:
  X-Api-Key: {brand_token}

{
    "status": "active",
    "platform": "custom",
    "webhook_url": "<https://somewebsite.com/api/ticket/created>",
    "trigger": "create"
}
```

### Ticket creation webhook

Once a ticket is created, a brand must send a request to the helpdesk ticket update endpoint:

```
POST /tickets/{helpdesk_ticket_id}
Headers:
  X-Api-Key: {brand_token}

{
    "external_ticket_id": "",
    "external_user_id": ""
}
```

### Ticket note callback

If a brand wants to send a message to the user, this endpoint can be used:

```
POST /tickets/{helpdesk_ticket_id}/events
Headers:
  X-Api-Key: {brand_token}

{
    "message": "Reply from the brand to emotive user",
    "status": "open",
    "event_time": "{{$randomDateRecent}}",
    "system_type": "custom"
}
```

## Ticket actions:

### Unsubscribe User

A brand can unsubscribe a user by sending a `#optout` or `#opt-out` message. This message won't be delivered to the user but will unsubscribe a user from the platform.

### Close ticket/conversation

Once the conversation was resolved and the brand decided to close it. Helpdesk API would need to receive a request to this endpoint:

```
POST /tickets/external/{external_ticket_id}/events
Headers:
  X-Api-Key: {brand_token}

{
    "status": "closed",
    "message": "",
    "event_time": "{{$randomDateRecent}}",
    "system_type": "custom"
}
```