Public API Documentation

This document describes the public-facing API endpoints for interacting with messages and threads. Each endpoint requires valid authentication (via x-api-key in the Headers header) to access. Below, you will find details on each available route, including request methods, request/response bodies, and example usage.

Authentication

This API requires a valid API Key in Headers. The typical format is:

x-api-key: API KEY

If you do not provide a valid token, the server will return a 401 Unauthorized error.

You can find your API X-API-KEY in yout settings dashboard:
https://app.gurusup.com/settings/integrations

GET /threads

Method: GET

Retrieves a list of threads (conversations) for the authenticated user's organization.

Request

• Headers: x-api-key: <api_key>

• Query Parameters: none

Response

Returns an array of thread objects in JSON format. Each thread includes essential thread metadata.

[
    {
        "thread": "e3b0c44298fc1c14...",
        "thread_fid": "some_unique_thread_identifier",
        ...
    },
    ...
]

Example

GET /threads
x-api-key: <api_key>

GET /threads/{thread_fid_hash}

Method: GET

Retrieves detailed information about a single thread, including all messages, identified by its hash.

Path Parameter

• thread_fid_hash: MD5-hash of the original thread_fid (string)

Request

• Headers: x-api-key: <api_key>

Response

Returns a single thread object in JSON, including all related messages.

{
    "thread": "d41d8cd98f00b204e9800998ecf8427e",
    "thread_fid": "some_unique_thread_identifier",
    "messages": [
        {
            "body": "Message content here",
            "thread_fid": "some_unique_thread_identifier",
            ...
        },
        ...
    ]

Example

GET /threads/d41d8cd98f00b204e9800998ecf8427e
x-api-key: <api_key>

POST /messages

Method: POST

Creates a new message (usually from a customer or user), then automatically triggers a reply from the system if configured. The final return value is the system’s message reply.

Request

• Headers: x-api-key: <api_key>

• Body (JSON): A PartialMessage object with required fields

Below are the key fields you can include:

| Field | Type | Notes |

|------------|--------|-------------------------------------------------|

| body | string | The textual content of the message. |

| user_fid | string | Unique identifier for the user sending the message. |

| thread_fid | string | An identifier for the thread this message belongs to. |

| lang | string | Language code (e.g., `en`, `es`). |

| subject | string | Optional subject/title for the message. |
| is_customer_support_agent | boolean | Identify if the message was sent by a support agent or a customer |

Response

Returns the newly created system-reply message in JSON format.

Example

POST /messages
x-api-key: <api_key>

GET /messages/{message_id}

Method: GET

Retrieve the details of a single message, by its unique database ID.

Path Parameter

• message_id: The MongoDB ObjectID (or string) for the message in question.

Request

• Headers: x-api-key: <api_key>

Response

Returns the message object in JSON format:

404 is returned if the message is not found.

Example

GET /messages/64f4f4a14abecf6c6eff59c3
Host: your-api-host.com
x-api-key: <api_key>

Webhook

The webhook is a URL that receives events from the Gurusup platform. The webhook will call the configured webhook URL with the event type and event data. A x-api-key header will also be sent with the value of the API key configured in the organization.

Event types

Send message event

Every time Gurusup tries to send a message to the user, a send message event will be sent to the webhook so your platform can actually send and store the message. The stored/sent message should be created in the same way as the original message.

Example of a send message event:

{
  "event_type": "send_message",
  "event_data": {
    "message_body": "Hello, how are you?",
    "subject": "Hello",
    "to": "1234567890",
    "thread_id": "1234567890",
    "in_reply_to_message": null
  }
}