Create a ticket using API
Introduction
In this tutorial, we’ll quickly go through one of the most used features by our app partners, creating tickets in Gorgias using API.
You can learn more about the ticket object here as we’ll focus more on defining specific parameters depending on the ticket channel you wish to use.
Step-by-Step Tutorial
Step 1: Configure the endpoint for the request
As you might already learn from the ticket object section, we’ll be using the tickets endpoint and POST method
--request POST \`
--url https://your-domain.gorgias.com/api/tickets \
--header 'accept: application/json' \
--header 'content-type: application/json'
Step 2: Authenticate your account
There are different levels of authentication depending on your app usage (private vs public). You can learn more here.
Step 3: Define the request body
We’ll dive a bit deeper into defining the request body for ticket creation calls depending on the channel you wish to use. Here’s an exampled list of available channels through which tickets can be created in Gorgias through the API:
- aircall
- API
- Facebook-mention
- Help-center
- Internal-note
- Phone
- SMS
The channels we’ll be focusing on are API, email, chat, phone, and SMS.
Please note that no matter which channel you use, the messages object
will be required.
Since a ticket in Gorgias cannot be created without a ticket message, the required parameters when creating a ticket via API will depend on the message channel chosen as well.
Also, please check these guidelines depending on whether the message under the ticket is incoming/outgoing.
API Ticket Channel
Required body params for ticket channel api and message channel api (incoming message):
- messages object
- sender object
- id and/or
- channel - api
- via - api
- from agent - false
- channel - api
- from agent - false
- via - api
Please note that if the message channel is set as API, our auto-reply rules won’t trigger for those tickets. Other rule actions such as auto-tag for example, will be triggered properly.
Also, rules that should trigger upon specific keywords inside the message body won’t trigger as well unless the message.stripped_text is defined.
Required body params for ticket channel api and message channel email (incoming message):
- messages object
- source object
- To object
- email address
- From object
- email address
- channel - email
- from agent - false
- via - api/email
- channel - api
- from agent - false
- via - api
Required body params for ticket channel api and message channel internal note (internal message):
- messages object
- sender object
- id and/or
- channel - internal-note
- via - internal-note
- from agent - true
- channel - api
- from agent - true
- via - api
Note that if the sender is not a user in Gorgias, the internal note will be sent from the ‘Gorgias Bot’. If you use an id or an email address of an existing user in Gorgias, it will be shown as sent by that specific user.
This will soon be deprecated so we highly recommend setting the sender as an existing user in Gorgias.
Request payload example:
{
"customer": {
"email": "[email protected]"
},
"messages": [
{
"sender": {
"email": "[email protected]"
},
"body_html": "Hello, this is a test ticket! ",
"body_text": "Hello, this is a test ticket! ",
"channel": "api",
"from_agent": false,
"stripped_text": "Hello, this is a test ticket! ",
"subject": "Test ticket",
"via": "api"
}
],
"meta": {
"meta": "example"
},
"tags": [
{
"name": "test"
}
],
"channel": "api",
"from_agent": false,
"status": "open",
"via": "api"
}
Email ticket channel
Required body params for ticket channel email and message channel email (incoming message):
- messages object
- source object
- To object
- email address
- From object
- email address
- channel - email
- from agent - false
- via - api/email
- channel - email
- from agent - false
- via - api/email
Request payload example:
{
"customer": {
"email": "[email protected]"
},
"messages": [
{
"sender": {
"email": "[email protected]"
},
"source": {
"to": [
{
"address": "[email protected]"
}
],
"from": {
"address": "[email protected]"
}
},
"body_html": "Hello, this is a test message! ",
"body_text": "Hello, this is a test message! ",
"channel": "email",
"from_agent": false,
"via": "api"
}
],
"meta": {
"meta_object": "example"
},
"tags": [
{
"name": "urgent"
},
{
"name": "test"
}
],
"channel": "email",
"from_agent": false,
"subject": "This is a test ticket",
"via":"api"
}
Phone ticket channel
Required body params for ticket channel phone and message channel phone (incoming message):
- messages object
- sender object
- id and/or
- phone number
- channel - phone
- via - api
- from agent - false
- channel - phone
- from agent - false
- via - api
{
"customer": {
"email": "[email protected]"
},
"messages": [
{
"source": {
"to": [
{
"address": "+123456789"
}
],
"from": {
"address": "+123456789"
},
"type": "phone"
},
"body_html": "Hello, this is a test phone ticket! ",
"body_text": "Hello, this is a test phone ticket! ",
"channel": "phone",
"from_agent": false,
"stripped_text": "Hello, this is a test phone ticket! ",
"via": "api"
}
],
"meta": {
"meta": "example"
},
"tags": [
{
"name": "test"
}
],
"channel": "phone",
"from_agent": false,
"status": "open",
"via": "api",
"subject": "Test ticket"
}
SMS ticket channel
Required body params for ticket channel SMS and message channel SMS (incoming message):
- messages object
- sender object
- id and/or
- phone number
- channel - sms
- via - api
- from agent - false
- channel - sms
- from agent - false
- via - api
{
"customer": {
"email": "[email protected]"
},
"messages": [
{
"source": {
"to": [
{
"address": "+123456789"
}
],
"from": {
"address": "+123456789"
},
"type": "phone"
},
"body_html": "Hello, this is a test phone ticket! ",
"body_text": "Hello, this is a test phone ticket! ",
"channel": "sms",
"from_agent": false,
"stripped_text": "Hello, this is a test phone ticket! ",
"via": "api"
}
],
"meta": {
"meta": "example"
},
"tags": [
{
"name": "test"
}
],
"channel": "sms",
"from_agent": false,
"status": "open",
"via": "api",
"subject": "Test ticket"
}
Updated 7 months ago