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:

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": "[e-mail]",
    "name": "John Doe",
    "customData": {
      "plan": "premium",
      "signupDate": "2024-01-15"
    }
  }'

Response:

{
  "_id": "507f1f77bcf86cd799439011",
  "id": "507f1f77bcf86cd799439011",
  "userId": "user_12345",
  "email": "[e-mail]",
  "name": "John Doe",
  "customData": {
    "plan": "premium",
    "signupDate": "2024-01-15"
  },
  "createdAt": "2024-01-20T10:30:00.000Z",
  "lastActivity": "2024-01-20T10:30:00.000Z"
}

Save the _id or id from the response - you’ll need it to create a ticket linked to this session.

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:

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:

{
  "_id": "507f1f77bcf86cd799439022",
  "id": "507f1f77bcf86cd799439022",
  "title": "Login button not working on mobile app",
  "type": "BUG",
  "session": {
    "_id": "507f1f77bcf86cd799439011",
    "email": "[e-mail]",
    "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"
}

Save the _id or id from the ticket response - you’ll need it to add comments to this ticket.

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):

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):

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):

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:

{
  "_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": "[e-mail]",
    "firstName": "Jane",
    "lastName": "Support"
  },
  "createdAt": "2024-01-20T11:00:00.000Z",
  "updatedAt": "2024-01-20T11:00:00.000Z"
}

Step 4: Create a Comment from Markdown

Instead of building the rich-text JSON structure yourself, you can send Markdown via the markdownComment field. The server converts it to rich text automatically, and it takes precedence over comment if both are set.

Endpoint: POST /v3/messages

Request:

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",
    "markdownComment": "We have identified the issue and deployed a fix. **Please update to version 2.3.2** to resolve this problem."
  }'

Messages created through this endpoint are always attributed to the user that owns the API key. It is not possible to create a comment on behalf of a customer (session) via this endpoint.