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
Email
Facebook
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
email

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
email

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