Create a new message in ticket via API

Introduction

In this tutorial, we will go through creating ticket messages via API. You can learn more about the ticket message object here as we’ll focus more on defining specific parameters depending on the type of message you wish to create (incoming/outgoing/internal note).

Step-by-Step Tutorial

Step 1: Configure the endpoint for the request

As you already learned from the ticket messages object, we’ll be using the messages endpoint that is tied to the tickets endpoint and POST method:

request POST \

url https://your-domain.gorgias.com/api/tickets/{ticket_id}/messages \

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. When creating a public application we advise using the OAuth flow for authentication for additional security and easier implementation.

Step 3: Define the request body

We’ll dive a bit deeper into defining the request body for ticket message creation calls depending on the type of message you wish to send.

There are two types of messages that you can create: public and internal notes.
Public messages can be incoming and outgoing while internal notes are always outgoing messages.

Incoming messages

from_agent set to false
sender must reference a customer
receiver should not be set

Request example:

request POST \
     url https://your-domain.gorgias.com/api/tickets/{ticket_id}/messages \
     header 'accept: application/json' \
     header 'content-type: application/json' \
     request payload: 
{
     "sender": {
          "email": "[email protected]"
     },
     "source": {
          "to": [
               {
                    "address": "[email protected]"
               }
          ],
          "from": {
               "address": "[email protected]"
          }
     },
     "body_html": "Hi, this is another test message! ",
     "body_text": "Hi, this is another test message! ",
     "channel": "email",
     "from_agent": false,
     "via": "api",
     "subject": "This is a test ticket"
}

Outgoing message

from_agent set to true
sender must reference a user
receiver must be a customer if specified

Request example:

request POST \
     url https://your-domain.gorgias.com/api/tickets/348149927/messages \
     header 'accept: application/json' \
     header 'content-type: application/json' \
     request payload:
{
     "receiver": {
          "email": "[email protected]"
     },
     "sender": {
          "email": "[email protected]"
     },
     "source": {
          "to": [
               {
                    "address": "[email protected]"
               }
          ],
          "from": {
               "address": "[email protected]"
          }
     },
     "body_html": "Hi, this is a test response!",
     "body_text": "Hi, this is a test response!",
     "channel": "email",
     "from_agent": true,
     "via": "api",
     "subject": "This is a test ticket"
}

🚧
Please note that the source.from.address parameter needs to be set to one of the existing email integrations connected to Gorgias for the email to be sent out.

Internal notes

from_agent set to true
sender must reference an existing user
receiver should not be set

request POST \
     url https://your-domain.gorgias.com/api/tickets/348149927/messages \
     header 'accept: application/json' \
     header 'content-type: application/json' \
     request payload:
{
     "sender": {
          "email": "[email protected]"
     },
     "body_html": "Hi, this is a test internal note!",
     "body_text": "Hi, this is a test internal note!",
     "channel": "internal-note",
     "from_agent": true,
     "via": "api",
     "subject": "This is a test ticket"
}