Resources

Tickets

This is an object representing your GuruSup inbox. You can retrieve it to see the tickets currently on your GuruSup account.

You can also retrieve a list of sender information that contributed to the message (sender email, sender name, source... )

ENDPOINTS           
POST /v1/tickets 
GET  /v1/tickets
PUT  /v1/tickets

Content type : JSON

The /v1/tickets endpoint allows you to manage tickets in your GuruSup account. You can create new tickets, retrieve existing ones, or update ticket details. This endpoint is essential for integrating GuruSup's ticketing system with your application.

Create a new Ticket

Endpoint Details

ENDPOINTS           
POST /v1/tickets

Content type : JSON

Request Structure

Text Fields:

external_id: Unique identifier for the ticket in your system.

Usage: Links the GuruSup ticket with a record in your database.

Required: Yes.

Format: Alphanumeric string

subject: Title of the ticket. Should summarize the issue.

Usage: Provides a brief summary of the issue or query.

Required: Yes.

Format: String

sender: Email address of the user creating the ticket.

Usage: Provides a brief summary of the issue or query.

Required: Yes.

Format: String

agent_id (optional): ID of the agent managing the ticket.

Usage: Links the ticket to a specific team member if applicable.

Required: No.

Format: String

agent_name: The name of the agent assigned to the ticket.

Usage: Provides a friendly reference to the agent instead of just using agent_id.

Required: No.

Format: String

messages: A list of messages related to the ticket.

Usage: Represents the content of the conversation associated with the ticket.

Required: Yes.

Format: Array of objects, where each object represents an individual message.

sources: The source of the ticket.

Usage: Identifies the origin of the ticket (e.g., 2 indicates it was created via the API).

Required: Yes.

Format: Integer

Message Fields:

external_id : A unique identifier for the message within the ticket.

Usage: Links the message with a record in your system for tracking or auditing purposes.

Required: Yes.

Format: Alphanumeric string

body: The content of the message.

Usage: Specifies the text of the message sent or received in the ticket.

Required: Yes.

Format: Text

is_agent: A boolean indicating whether the message was sent by an agent.

Usage: Differentiates between messages from the customer (false) and from the agent (true).

Required: Yes.

Format: true or false

received_at: The date and time the message was received.

Usage: Records the exact time the message was sent or received.

Required: Yes.

Format: ISO 8601 (e.g., "2024-11-15T10:30:00Z").

Example POST Body

Request: Create a new Ticket

POST /v1/tickets
{
  "external_id": "12345",
  "subject": "Issue with product delivery",
  "sender": "customer@example.com",
  "agent_id": "67890",
  "agent_name": "John Doe",
  "messages": [
    {
      "external_id": "msg_001",
      "body": "I haven't received my product yet.",
      "is_agent": false,
      "received_at": "2024-11-15T10:30:00Z"
    }
  ],
  "sources": 2
}

Response:

{
  "status": "success",
  "ticket_id": "ticket_123",
  "message": "Ticket created successfully"
}

Update Ticket

ENDPOINTS                                                           JSON
GET  /v1/tickets/{ticket_id or external_id}

The /v1/tickets endpoint allows you to update an existing ticket in the system. Below are the fields required or optional for the update operation:

Tickets Fields:

subject: The subject or title of the ticket. Provides a brief summary of the issue or query.

Usage: Helps quickly identify the ticket's purpose.

Required:No

Format: String

sender: The email address of the person who submitted the ticket.

Usage: Identifies the customer submitting the request.

Required: No

Format: String

sender_name: The name of the sender (customer).

Usage: Adds clarity by associating a name with the ticket.

Required: No

Format: String

agent_id: The ID of the agent assigned to manage the ticket.

Usage: Links the ticket to a specific agent.

Required: No

Format: String

agent: The email address of the agent assigned to the ticket.

Usage: Provides the agent's contact information.

Required:No

Format: Email

agent_name: The name of the agent assigned to the ticket.

Usage: Makes it easier to identify the agent managing the ticket.

Required: No

Format: String

messages: A list of messages associated with the ticket.

Usage: Contains the history of communication between the sender and the agent.

Required: Yes

Format: Array of message objects

Message Fields:

external_id: A unique identifier for the message in your system.

Usage: Tracks the message and links it to your internal records.

Required: Yes

Format: Alphanumeric string (e.g., "msg_001")

body: The content of the message.

Usage: Represents the actual text sent or received in the conversation.

Required: Yes

Format: String (e.g., "I need help with my order.")

is_agent: Boolean indicating whether the message was sent by an agent.

Usage: Differentiates messages from the customer (false) and the agent (true).

Required: Yes

Format: true or false

received_at: The date and time when the message was received.

Usage: Tracks when each message was sent or received to maintain a timeline.

Required: Yes

Format: ISO 8601 (e.g., "2024-11-15T10:30:00Z")

Example:

```
{"external_id": "5001",
 "subject": "Info Tour Roma",
 "sender": "victor@example.com",
 "sender_name": "Victor J Martin",
 "messages": [{"external_id": "15151w5e",
               "body": "Hola, me llamo Victor,
                        ¿ podría hacer un tour para
                        el jueves en Roma ? muchas gracias",
               "is_agent": false,
               "received_at: "2024-05-31T16:03:00"},
               {"external_id": "15151w5e",
               "body": "Claro, a las 11 tienes uno",
               "is_agent": true,
               "received_at: "2024-05-31T16:03:00"}],
 "source": 2,
 "agent_id": "4600",
 "agent": "fede@agent.com",
 "agent_name": "Fede Agent"}
```

Final Notes

This documentation is designed to give you everything you need to start using the GuruSup API's Resources endpoints effectively. For further questions, contact support@gurusup.com.