Set up a Custom Helpdesk Integration

You can find developer documentation here.

Required Configuration

Brand Token

Get ticket system ID from this endpoint:

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

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"
}

Get Started

Learn

Best Practices

Required Configuration

Brand Token

Generate Helpdesk Brand Token

Token usage

Brand webhooks

Define webhooks

Ticket creation webhook

Ticket note callback

Ticket actions:

Unsubscribe User

Close ticket/conversation

​Required Configuration

​Brand Token

​Generate Helpdesk Brand Token

​Token usage

​Brand webhooks

​Define webhooks

​Ticket creation webhook

​Ticket note callback

​Ticket actions:

​Unsubscribe User

​Close ticket/conversation

Required Configuration

Brand Token

Generate Helpdesk Brand Token

Token usage

Brand webhooks

Define webhooks

Ticket creation webhook

Ticket note callback

Ticket actions:

Unsubscribe User

Close ticket/conversation