Ticket

All communication within Omnidesk is facilitated through tickets. Tickets can contain messages (displayed on the timeline), have a status (like new, open or solved) and be assigned to groups. These and many other options are available through the API.

Get timeline

GET https://account.omnidesk.com/api/v2/ticket/:ticketID

This method will show the ticket and corresponding timeline, including status, tags, assignment, messages etc.

Path Parameters

Name

Type

Description

getTicketHistory

boolean

Also get the event history on the ticket

{
    "type": "item",
    "item": {
        "assigned_group_id": 10003,
        "assigned_user_id": 0,
        "channel_account_id": "0",
        "channel_id": 1,
        "closed_at": null,
        "created_at": "2019-09-28 22:06:16",
        "customer_id": 626822,
        "direction": "inbound",
        "external_gui_url": "https://guiurl.brand.com/?ticketID=858462#20164564646592575",
        "external_id": "BFFDAFF1-6E3F-2244-93EE-65A9CF3D0ECE.1",
        "form_id": null,
        "from": "thomas@test.com",
        "from_name": "",
        "grade_by_customer": null,
        "icon": "e-mail",
        "last_update": "2019-09-28 22:06:16",
        "last_update_agent": null,
        "last_update_customer": "2019-09-28 22:06:16",
        "priority": "medium",
        "show_timeline": 1,
        "sla_breach_customer_wait_time": null,
        "sla_breach_first_reply_time": "2019-10-01 12:00:00",
        "sla_breach_next_reply_time": null,
        "sla_breach_user_work_time": null,
        "sla_next_breach": "2019-10-01 12:00:00",
        "sla_next_breach_current_status": "active",
        "sla_policy_id": 5,
        "snooze_time": null,
        "snooze_time_sent": null,
        "title": "vraag van Thomas",
        "to": "service@mybrand.com",
        "to_name": "",
        "status": "new",
        "id": 858462,
        "channel_name": "e-mail",
        "channel_icon": "e-mail",
        "brand_name": "MyBrand",
        "brand_id": 2,
        "timeline": [
            {
                "id": 4090647,
                "ticket_id": 858462,
                "item_type": "assigned_group_id",
                "item_type_id": "10003",
                "description": "Assigned to Servicee",
                "initiated_by": "trigger: Assign to service",
                "created_at": "2019-09-28 22:06:23",
                "type": "event"
            },
            {
                "to": null,
                "from": null,
                "image": "",
                "created_at": "2019-09-28 23:30:13",
                "pinned": 0,
                "id": "3143281",
                "channel_name": null,
                "channel_icon": null,
                "type": "note",
                "status_new": "open",
                "user_id": 254,
                "user_name": "marleen",
                "user_avatar": "",
                "channel_id": 0,
                "direction": "",
                "content": "My intern note on this ticket",
                "ticket_id": 858462,
                "external_id": null,
                "from_name": "",
                "to_name": "",
                "meta_data": "[]",
                "in_queue": 0,
                "send_at": null,
                "files": []
            },
            {
                "to": "service@mybrand.com",
                "from": "thomas@test.com",
                "image": "",
                "created_at": "2019-09-28 22:06:17",
                "pinned": 0,
                "id": "3143690",
                "channel_name": "e-mail",
                "channel_icon": "e-mail",
                "type": "message",
                "status_new": "new",
                "user_id": 0,
                "user_name": "Anonymous",
                "user_avatar": "",
                "channel_id": 1,
                "direction": "inbound",
                "content": "<!DOCTYPE html PUBLIC \"-//W3C//DTD HTML 4.0 Transitional//EN\" \"http://www.w3.org/TR/REC-html40/loose.dtd\">\n<html><body><p><b>HTML</b> email content</p></body></html>\n",
                "ticket_id": 858462,
                "external_id": "BFFDAFF1-6E3F-2244-93EE-65A9CF3D0ECE.1",
                "from_name": "",
                "to_name": "",
                "meta_data": "{\"to\":[{\"address\":\"service@mybrand.com\",\"name\":\"\"}]}",
                "in_queue": 0,
                "send_at": null,
                "content_whole": "<b>HTML</b> content",
                "email_details": "to: service@mybrand.com",
                "email_show_reply_all": false,
                "files": []
            }
        ],
        "following": false,
        "sla_next_breach_seconds": 222706,
        "customer": {
            "id": 626822,
            "brand_id": 2,
            "external_primary_id": "20164564646592575",
            "firstname": "T",
            "lastname": "van Test",
            "created_at": "2019-09-28 22:06:16"
        },
        "customer_channels": [
            {
                "id": 1194929,
                "brand_id": 2,
                "customer_id": 624822,
                "channel_id": 1,
                "unique_reference": "thomas@test.com",
                "linked_by_user_id": 0,
                "name": "e-mail",
                "icon": "e-mail"
            },
            {
                "id": 1194930,
                "brand_id": 2,
                "customer_id": 626822,
                "channel_id": 2,
                "unique_reference": "+3164568456",
                "linked_by_user_id": 0,
                "name": "telephone",
                "icon": "telephone"
            }
        ],
        "tags": "",
        "customer_custom_fields": [],
        "assign_options_groups": [
            {
                "id": 10002,
                "name": "Finance"
            },
            {
                "id": 10003,
                "name": "Customer Support"
            }  
        ],
        "assign_options_users": [
            {
                "id": 1,
                "name": "thomas"
            },
            {
                "id": 2,
                "name": "marleen"
            }
        ],
        "original_channel_id": 0
    }
}

Create a ticket

POST https://account.omnidesk.com/api/v2/ticket

Please note that the to and from should be inverted when using direction outbound.

Request Body

Name

Type

Description

assignedGroupID

integer

id of the group assigned to the ticket

string

to address, for instance helpdesk@brand.com

from

string

from address, for instance customer@freemail.com

direction

string

inbound or outbound

channelID

integer

see our channelID documentation, 1 = email

brandID

integer

brandID can be viewed in settings > brands

title

string

title of the ticket

formID

integer

form id you want to attach to the ticket

{"type":"item","item":{"id":"", "other ticket fields": ...}}

After that you can start adding information to the ticket. As an example we will set the status of the ticket below or add a message or update form fields (see the subpages: message, form field, etc).

Update Ticket

PUT https://account.omnidesk.com/api/v2/ticket/:ticketID

Provide the fields you want to update. All fields are optional. If you do not provide a certain field it will not get updated.

Request Body

Name

Type

Description

title

string

status

string

Status changes of a ticket will trigger updated trigger

externalPrimaryID

string

Your primary (customer) ID, if the customer does not exist the ticket will be set to no customer.

{"type": "result", "message": "Ticket updated."}

Set the status of a ticket

POST https://account.omnidesk.com/api/v2/ticket/setstatus

Status updates will trigger the updated trigger.

Request Body

Name

Type

Description

ticketIDs[]

integer

List of ticket ids the change should be applied to.

status

string

Options: new, open, pending, holding, solved, closed

{    "type": "result",    "message": "Ticket status is updated."}

NextMessage

Last updated 3 months ago

Ticket

Get timeline

GET https://account.omnidesk.com/api/v2/ticket/:ticketID

This method will show the ticket and corresponding timeline, including status, tags, assignment, messages etc.

Path Parameters

Name

Type

Description

getTicketHistory

boolean

Also get the event history on the ticket

{
    "type": "item",
    "item": {
        "assigned_group_id": 10003,
        "assigned_user_id": 0,
        "channel_account_id": "0",
        "channel_id": 1,
        "closed_at": null,
        "created_at": "2019-09-28 22:06:16",
        "customer_id": 626822,
        "direction": "inbound",
        "external_gui_url": "https://guiurl.brand.com/?ticketID=858462#20164564646592575",
        "external_id": "BFFDAFF1-6E3F-2244-93EE-65A9CF3D0ECE.1",
        "form_id": null,
        "from": "thomas@test.com",
        "from_name": "",
        "grade_by_customer": null,
        "icon": "e-mail",
        "last_update": "2019-09-28 22:06:16",
        "last_update_agent": null,
        "last_update_customer": "2019-09-28 22:06:16",
        "priority": "medium",
        "show_timeline": 1,
        "sla_breach_customer_wait_time": null,
        "sla_breach_first_reply_time": "2019-10-01 12:00:00",
        "sla_breach_next_reply_time": null,
        "sla_breach_user_work_time": null,
        "sla_next_breach": "2019-10-01 12:00:00",
        "sla_next_breach_current_status": "active",
        "sla_policy_id": 5,
        "snooze_time": null,
        "snooze_time_sent": null,
        "title": "vraag van Thomas",
        "to": "service@mybrand.com",
        "to_name": "",
        "status": "new",
        "id": 858462,
        "channel_name": "e-mail",
        "channel_icon": "e-mail",
        "brand_name": "MyBrand",
        "brand_id": 2,
        "timeline": [
            {
                "id": 4090647,
                "ticket_id": 858462,
                "item_type": "assigned_group_id",
                "item_type_id": "10003",
                "description": "Assigned to Servicee",
                "initiated_by": "trigger: Assign to service",
                "created_at": "2019-09-28 22:06:23",
                "type": "event"
            },
            {
                "to": null,
                "from": null,
                "image": "",
                "created_at": "2019-09-28 23:30:13",
                "pinned": 0,
                "id": "3143281",
                "channel_name": null,
                "channel_icon": null,
                "type": "note",
                "status_new": "open",
                "user_id": 254,
                "user_name": "marleen",
                "user_avatar": "",
                "channel_id": 0,
                "direction": "",
                "content": "My intern note on this ticket",
                "ticket_id": 858462,
                "external_id": null,
                "from_name": "",
                "to_name": "",
                "meta_data": "[]",
                "in_queue": 0,
                "send_at": null,
                "files": []
            },
            {
                "to": "service@mybrand.com",
                "from": "thomas@test.com",
                "image": "",
                "created_at": "2019-09-28 22:06:17",
                "pinned": 0,
                "id": "3143690",
                "channel_name": "e-mail",
                "channel_icon": "e-mail",
                "type": "message",
                "status_new": "new",
                "user_id": 0,
                "user_name": "Anonymous",
                "user_avatar": "",
                "channel_id": 1,
                "direction": "inbound",
                "content": "<!DOCTYPE html PUBLIC \"-//W3C//DTD HTML 4.0 Transitional//EN\" \"http://www.w3.org/TR/REC-html40/loose.dtd\">\n<html><body><p><b>HTML</b> email content</p></body></html>\n",
                "ticket_id": 858462,
                "external_id": "BFFDAFF1-6E3F-2244-93EE-65A9CF3D0ECE.1",
                "from_name": "",
                "to_name": "",
                "meta_data": "{\"to\":[{\"address\":\"service@mybrand.com\",\"name\":\"\"}]}",
                "in_queue": 0,
                "send_at": null,
                "content_whole": "<b>HTML</b> content",
                "email_details": "to: service@mybrand.com",
                "email_show_reply_all": false,
                "files": []
            }
        ],
        "following": false,
        "sla_next_breach_seconds": 222706,
        "customer": {
            "id": 626822,
            "brand_id": 2,
            "external_primary_id": "20164564646592575",
            "firstname": "T",
            "lastname": "van Test",
            "created_at": "2019-09-28 22:06:16"
        },
        "customer_channels": [
            {
                "id": 1194929,
                "brand_id": 2,
                "customer_id": 624822,
                "channel_id": 1,
                "unique_reference": "thomas@test.com",
                "linked_by_user_id": 0,
                "name": "e-mail",
                "icon": "e-mail"
            },
            {
                "id": 1194930,
                "brand_id": 2,
                "customer_id": 626822,
                "channel_id": 2,
                "unique_reference": "+3164568456",
                "linked_by_user_id": 0,
                "name": "telephone",
                "icon": "telephone"
            }
        ],
        "tags": "",
        "customer_custom_fields": [],
        "assign_options_groups": [
            {
                "id": 10002,
                "name": "Finance"
            },
            {
                "id": 10003,
                "name": "Customer Support"
            }  
        ],
        "assign_options_users": [
            {
                "id": 1,
                "name": "thomas"
            },
            {
                "id": 2,
                "name": "marleen"
            }
        ],
        "original_channel_id": 0
    }
}

Create a ticket

POST https://account.omnidesk.com/api/v2/ticket

Please note that the to and from should be inverted when using direction outbound.

Request Body

Name

Type

Description

assignedGroupID

integer

id of the group assigned to the ticket

string

to address, for instance helpdesk@brand.com

from

string

from address, for instance customer@freemail.com

direction

string

inbound or outbound

channelID

integer

see our channelID documentation, 1 = email

brandID

integer

brandID can be viewed in settings > brands

title

string

title of the ticket

formID

integer

form id you want to attach to the ticket

{"type":"item","item":{"id":"", "other ticket fields": ...}}

Update Ticket

PUT https://account.omnidesk.com/api/v2/ticket/:ticketID

Provide the fields you want to update. All fields are optional. If you do not provide a certain field it will not get updated.

Request Body

Name

Type

Description

title

string

status

string

Status changes of a ticket will trigger updated trigger

externalPrimaryID

string

Your primary (customer) ID, if the customer does not exist the ticket will be set to no customer.

{"type": "result", "message": "Ticket updated."}

Set the status of a ticket

POST https://account.omnidesk.com/api/v2/ticket/setstatus

Status updates will trigger the updated trigger.

Request Body

Name

Type

Description

ticketIDs[]

integer

List of ticket ids the change should be applied to.

status

string

Options: new, open, pending, holding, solved, closed

{    "type": "result",    "message": "Ticket status is updated."}

NextMessage

Last updated 3 months ago