> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gleap.io/llms.txt
> Use this file to discover all available pages before exploring further.

# API Samples

This page demonstrates the most common API workflow: creating or finding a session, creating a ticket, and adding a comment to that ticket.

## Common Flow Example

This example walks through a complete workflow that you'll use frequently when integrating with the Gleap API.

### Step 1: Create or Find a Session

First, create a session to represent a user or contact. If a session with the same `userId` already exists, you can use that session ID instead.

**Endpoint:** `POST /v3/sessions`

**Request:**

```bash theme={null}
curl -X POST https://api.gleap.io/v3/sessions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Project: YOUR_PROJECT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_12345",
    "email": "john.doe@example.com",
    "name": "John Doe",
    "customData": {
      "plan": "premium",
      "signupDate": "2024-01-15"
    }
  }'
```

**Response:**

```json theme={null}
{
  "_id": "507f1f77bcf86cd799439011",
  "id": "507f1f77bcf86cd799439011",
  "userId": "user_12345",
  "email": "john.doe@example.com",
  "name": "John Doe",
  "customData": {
    "plan": "premium",
    "signupDate": "2024-01-15"
  },
  "createdAt": "2024-01-20T10:30:00.000Z",
  "lastActivity": "2024-01-20T10:30:00.000Z"
}
```

<Info>
  Save the `_id` or `id` from the response - you'll need it to create a ticket linked to this session.
</Info>

### Step 2: Create a Ticket

Now create a ticket and link it to the session you just created. The ticket represents a support request, bug report, or feature request.

**Endpoint:** `POST /v3/tickets`

**Request:**

```bash theme={null}
curl -X POST https://api.gleap.io/v3/tickets \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Project: YOUR_PROJECT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Login button not working on mobile app",
    "type": "BUG",
    "session": "507f1f77bcf86cd799439011",
    "formData": {
      "description": "Users are unable to log in when clicking the login button on iOS devices. The button appears to be unresponsive."
    }
  }'
```

**Response:**

```json theme={null}
{
  "_id": "507f1f77bcf86cd799439022",
  "id": "507f1f77bcf86cd799439022",
  "title": "Login button not working on mobile app",
  "type": "BUG",
  "session": {
    "_id": "507f1f77bcf86cd799439011",
    "email": "john.doe@example.com",
    "name": "John Doe"
  },
  "formData": {
    "description": "Users are unable to log in when clicking the login button on iOS devices. The button appears to be unresponsive."
  },
  "createdAt": "2024-01-20T10:35:00.000Z",
  "updatedAt": "2024-01-20T10:35:00.000Z"
}
```

<Info>
  Save the `_id` or `id` from the ticket response - you'll need it to add comments to this ticket.
</Info>

### Step 3: Create a Comment

Add a comment to the ticket. Comments can be simple text or rich formatted content. You can also attach files.

**Endpoint:** `POST /v3/messages`

**Request (Simple Text Comment):**

```bash theme={null}
curl -X POST https://api.gleap.io/v3/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Project: YOUR_PROJECT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "ticket": "507f1f77bcf86cd799439022",
    "comment": "Thank you for reporting this issue. We are looking into it and will update you soon."
  }'
```

**Request (Rich Formatted Comment with Attachments):**

```bash theme={null}
curl -X POST https://api.gleap.io/v3/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Project: YOUR_PROJECT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "ticket": "507f1f77bcf86cd799439022",
    "comment": {
      "type": "doc",
      "content": [
        {
          "type": "paragraph",
          "content": [
            {
              "type": "text",
              "text": "We have identified the issue and deployed a fix. "
            },
            {
              "type": "text",
              "marks": [
                {
                  "type": "bold"
                }
              ],
              "text": "Please update to version 2.3.2"
            },
            {
              "type": "text",
              "text": " to resolve this problem."
            }
          ]
        },
        {
          "type": "paragraph",
          "content": [
            {
              "type": "text",
              "text": "If you continue to experience issues, please let us know."
            }
          ]
        }
      ]
    },
    "attachments": [
      {
        "name": "fix-screenshot.png",
        "url": "https://example.com/screenshots/fix-screenshot.png",
        "type": "image/png"
      }
    ]
  }'
```

**Request (Internal Note):**

```bash theme={null}
curl -X POST https://api.gleap.io/v3/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Project: YOUR_PROJECT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "ticket": "507f1f77bcf86cd799439022",
    "comment": "This is a high-priority issue affecting multiple users. Escalating to the mobile team.",
    "isNote": true
  }'
```

**Response:**

```json theme={null}
{
  "_id": "507f1f77bcf86cd799439033",
  "id": "507f1f77bcf86cd799439033",
  "ticket": "507f1f77bcf86cd799439022",
  "comment": {
    "type": "doc",
    "content": [
      {
        "type": "paragraph",
        "content": [
          {
            "type": "text",
            "text": "We have identified the issue and deployed a fix. "
          },
          {
            "type": "text",
            "marks": [
              {
                "type": "bold"
              }
            ],
            "text": "Please update to version 2.3.2"
          },
          {
            "type": "text",
            "text": " to resolve this problem."
          }
        ]
      }
    ]
  },
  "type": "TEXT",
  "attachments": [
    {
      "name": "fix-screenshot.png",
      "url": "https://example.com/screenshots/fix-screenshot.png",
      "type": "image/png"
    }
  ],
  "user": {
    "_id": "507f1f77bcf86cd799439044",
    "email": "support@example.com",
    "firstName": "Jane",
    "lastName": "Support"
  },
  "createdAt": "2024-01-20T11:00:00.000Z",
  "updatedAt": "2024-01-20T11:00:00.000Z"
}
```

### Step 4: Create a Customer Comment

You can also create a comment that appears as if it's from the customer (session) rather than from an agent. This is useful when you want to add a comment on behalf of the customer.

**Endpoint:** `POST /v3/messages`

**Request:**

```bash theme={null}
curl -X POST https://api.gleap.io/v3/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Project: YOUR_PROJECT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "ticket": "507f1f77bcf86cd799439022",
    "comment": "I tried updating the app but the issue still persists. Can you help?",
    "session": "507f1f77bcf86cd799439011"
  }'
```

**Response:**

```json theme={null}
{
  "_id": "507f1f77bcf86cd799439044",
  "id": "507f1f77bcf86cd799439044",
  "ticket": "507f1f77bcf86cd799439022",
  "comment": "I tried updating the app but the issue still persists. Can you help?",
  "type": "TEXT",
  "session": {
    "_id": "507f1f77bcf86cd799439011",
    "email": "john.doe@example.com",
    "name": "John Doe"
  },
  "createdAt": "2024-01-20T11:30:00.000Z",
  "updatedAt": "2024-01-20T11:30:00.000Z"
}
```

<Info>
  By including the `session` field in the request, the comment will appear as if it came from the customer (session) rather than from an agent (user). Omit the `session` field to create an agent comment.
</Info>