Unified Messaging Interface API

Unified Messaging Interface (UMI) — API Documentation¶

Overview¶

The Unified Messaging Interface (UMI) lets you route messages from any external messaging channel (email, Zendesk, WhatsApp, Slack, custom systems, etc.) into the Giosg platform and receive replies back through webhooks.

Why use UMI?¶

Integrating directly with the full Giosg chat API is powerful but requires managing chat sessions, memberships, visitor objects, and real-time events yourself. UMI removes that complexity. It gives you:

Automatic chat-session lifecycle management — send a message with a thread_id and UMI creates, reuses, or rotates chat sessions for you.
Simple webhooks — when an agent (human or AI) replies, or when a reply suggestion is generated, your endpoint receives a single JSON POST with all the context you need.
Minimal integration surface — three API endpoints (register channel, send messages, close session) plus one or two webhook handlers on your side.

UMI intentionally exposes a limited feature set. If you need fine-grained control (e.g., attachments, interactive buttons, custom membership management), you can always use the full Giosg v5 APIs alongside UMI.

Authentication¶

All endpoints require authentication. Supported methods:

Method	Header
Bearer token (access token)	`Authorization: Bearer <token>`
User API token	`Authorization: Token <api_token>`

1. Messaging Channel Configuration API¶

1.1 Register Messaging Channel¶

Create a new messaging channel configuration that links an external messaging channel to a Giosg platform and routing system.

Endpoint: POST /api/v5/orgs/<organization_id>/unified_messaging

Permissions: settings scope is required for the user making the request.

Request Payload¶

{
  "name": "Support Email Channel",
  "messaging_channel": "email",
  "room_id": "789e4567-e89b-12d3-a456-426614174111",
  "reply_webhook_url": "https://your-server.com/webhooks/giosg-replies",
  "max_retry_count": 3
}

Field	Type	Required	Default	Description
`name`	string	Yes	—	Human-readable name for this configuration (max 255 chars). Cannot be blank.
`messaging_channel`	string	Yes	—	Channel type identifier (max 64 chars). Free-form string, e.g. `"email"`, `"zendesk"`, `"whatsapp"`, `"slack"`.
`room_id`	UUID	Yes	—	UUID of the Giosg room where incoming messages will be routed. Must belong to the same organization.
`reply_webhook_url`	string	Yes	—	URL that will receive webhook POST requests when agents (human or AI) reply or reply suggestions are created (max 2048 chars).
`max_retry_count`	integer	No	`3`	Maximum number of retry attempts for failed webhook deliveries.

Response — `201 Created`¶

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Support Email Channel",
  "messaging_channel": "email",
  "organization_id": "123e4567-e89b-12d3-a456-426614174000",
  "room_id": "789e4567-e89b-12d3-a456-426614174111",
  "reply_webhook_url": "https://your-server.com/webhooks/giosg-replies",
  "max_retry_count": 3,
  "created_at": "2026-03-01T09:00:00.000Z",
  "modified_at": "2026-03-01T09:00:00.000Z"
}

Field	Type	Description
`id`	UUID	Unique identifier for this channel configuration (read-only).
`name`	string	Name of this channel configuration.
`messaging_channel`	string	Channel type identifier.
`organization_id`	UUID	Organization that owns this configuration (read-only).
`room_id`	UUID	Room where messages are routed.
`reply_webhook_url`	string	Webhook URL for outgoing notifications.
`max_retry_count`	integer	Max retries for failed webhooks.
`created_at`	string (ISO 8601)	When the configuration was created (read-only).
`modified_at`	string (ISO 8601)	When the configuration was last modified (read-only).

Error Responses¶

Status	Description
`400`	Invalid payload, missing required fields, room not found, or room belongs to different organization.
`403`	Insufficient permissions.
`404`	Organization not found.

1.2 List Messaging Channels¶

List all registered messaging channel configurations for an organization.

Endpoint: GET /api/v5/orgs/<organization_id>/unified_messaging

Query Parameters¶

Parameter	Type	Description
`ordering`	string	Sort order. Allowed values: `created_at`, `-created_at`, `modified_at`, `-modified_at`, `messaging_channel`. Default: `-created_at`.
`cursor`	string	Pagination cursor for next/previous page.

Response — `200 OK`¶

{
  "next": "https://api.giosg.com/api/v5/orgs/.../unified_messaging?cursor=abc",
  "previous": null,
  "results": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Support Email Channel",
      "messaging_channel": "email",
      "organization_id": "123e4567-e89b-12d3-a456-426614174000",
      "room_id": "789e4567-e89b-12d3-a456-426614174111",
      "reply_webhook_url": "https://your-server.com/webhooks/giosg-replies",
      "max_retry_count": 3,
      "created_at": "2026-03-01T09:00:00.000Z",
      "modified_at": "2026-03-01T09:00:00.000Z"
    }
  ]
}

2. Message API¶

2.1 Create Messages¶

Send one or more messages from an external channel into Giosg. The API automatically manages thread-to-session mapping: it creates new chat sessions when needed and reuses existing ones when the thread is still active.

Endpoint: POST /api/v5/orgs/<organization_id>/unified_messaging/<config_id>/messages

Permissions: settings scope is required for the user making the request.

Request Payload¶

{
  "messages": [
    {
      "body": "Hello, I need help with my order!",
      "thread_id": "email-thread-12345",
      "sender_id": "customer@example.com",
      "message_id": "msg-001-2026-03-01",
      "sender_type": "visitor",
      "selected_reply_suggestion_id": null
    }
  ],
  "skip_waiting_state": false,
  "close_session": false,
  "variables": {
    "customer_name": "John Doe",
    "customer_email": "john@example.com"
  }
}

Top-level fields¶

Field	Type	Required	Default	Description
`messages`	array	Yes	—	Array of message objects (at least one required). All messages in a batch must share the same `thread_id`.
`skip_waiting_state`	boolean	No	`false`	If `true`, the chat session will not be placed in the waiting queue. Useful for automated messages or system notifications.
`close_session`	boolean	No	`false`	If `true`, the chat session will be closed after creating the messages. Useful for when importing old threads from another system.
`variables`	object	No	—	Key-value pairs (string → string) to save as visitor variables. Keys with `null` values are ignored.

Message object fields¶

Field	Type	Required	Default	Description
`body`	string	Yes	—	Message text content. Cannot be blank.
`thread_id`	string	Yes	—	External thread identifier (e.g., email subject, ticket ID). Max 512 chars. All messages in the batch must have the same value.
`sender_id`	string	Yes	—	Sender identifier. Max 512 chars. For `sender_type: "visitor"` this is a free-form string (e.g., email address). For `sender_type: "user"` this must be the UUID of a user in the same organization.
`message_id`	string	Yes	—	Unique message identifier from the external system. Max 512 chars. Currently stored for logging purposes but may be used later on for deduplication or other features.
`sender_type`	string	No	`"visitor"`	`"visitor"` for messages from external contacts, `"user"` for messages from Giosg agents.
`selected_reply_suggestion_id`	UUID or null	No	`null`	If the message was based on a reply suggestion, pass its UUID here. Only valid for `sender_type: "user"` and only for existing conversations (not new sessions). The reply suggestion must belong to the same chat session and organization.

Session lifecycle behavior¶

Scenario	What happens
New `thread_id`	Creates a new chat session, a new visitor, visitor membership, and a thread-to-session mapping.
Existing `thread_id`, active session	Reuses the existing chat session and adds the message(s).
Existing `thread_id`, ended session	Creates a new chat session, updates the mapping, and creates the message(s).

Response — `201 Created`¶

{
  "chat_id": "b7c2c298-0370-4381-a078-c60cfd255e1a",
  "mapping_id": "3fe1fecd-dc82-4891-97d7-241a029b5aab",
  "message_ids": [
    "b852e953-baf7-4e5f-accc-53b610f0b070"
  ],
  "messages_created": 1,
  "is_new_session": true
}

Field	Type	Description
`chat_id`	UUID	ID of the chat session where the messages were created.
`mapping_id`	UUID	ID of the thread-to-session mapping.
`message_ids`	array of UUIDs	IDs of the created chat messages, in the same order as the input.
`messages_created`	integer	Number of messages successfully created.
`is_new_session`	boolean	`true` if a new chat session was created, `false` if an existing one was reused.

Error Responses¶

Status	Description
`400`	Missing required fields, blank body, mismatched `thread_id` values, invalid `sender_type`, invalid `sender_id` for user messages, invalid `selected_reply_suggestion_id`, or reply suggestion used for a new conversation / visitor message.
`403`	Insufficient permissions.
`404`	Channel configuration not found or belongs to a different organization.

2.2 Close Session¶

Explicitly close an active chat session for a given thread. This is useful when the external system knows the conversation is finished.

Endpoint: POST /api/v5/orgs/<organization_id>/unified_messaging/<config_id>/close_session

Permissions: settings scope is required for the user making the request.

Request Payload¶

{
  "thread_id": "email-thread-12345"
}

Field	Type	Required	Description
`thread_id`	string	Yes	External thread identifier whose associated chat session should be closed. Max 512 chars.

Response — `200 OK`¶

{
  "chat_session_id": "a1b2c3d4-5678-90ab-cdef-123456789012",
  "thread_id": "email-thread-12345",
  "message": "Chat session closed successfully",
  "is_ended": true
}

Field	Type	Description
`chat_session_id`	UUID	ID of the closed chat session.
`thread_id`	string	The thread identifier that was closed.
`message`	string	Human-readable status message. If the session was already closed, this reads `"Chat session was already closed"`.
`is_ended`	boolean	Always `true`.

Behavior notes¶

If the session is already closed, the endpoint returns 200 with "Chat session was already closed" — it is idempotent.
Once closed, any new messages sent with the same thread_id will create a new chat session.

Error Responses¶

Status	Description
`400`	Missing `thread_id`.
`403`	Insufficient permissions.
`404`	Thread ID not found, channel configuration not found, or no session exists for the thread. Response will have `detail` attribute which describes the error reason.

3. Webhooks (Giosg → Your System)¶

When events happen inside Giosg on chat sessions created through UMI, webhook notifications are sent as HTTP POST requests to the reply_webhook_url configured on the channel. Two event types are supported:

Event Type	Trigger
`message_created`	An agent (human or AI) sends a message in the chat session.
`reply_suggestion_created`	An AI agent creates a reply suggestion for a visitor message.

Webhook delivery¶

Property	Value
HTTP method	`POST`
Content-Type	`application/json`
Timeout	5 seconds
Retry strategy	Exponential backoff: `2^n + random 0–1 s` jitter
Max retries	Configurable per channel (`max_retry_count`, default 3)
Success	Any HTTP `2xx` response
Failure	HTTP `4xx` / `5xx` or network error triggers retry

Your webhook endpoint should respond within 5 seconds with an HTTP 2xx status to acknowledge receipt.

Webhook trigger conditions¶

Webhooks are triggered when: - An agent (human or AI) creates a normal message (type: "msg") in a chat session linked to a ThreadChatSessionMapping. - A ChatReplySuggestion is created for a message in a chat session linked to a ThreadChatSessionMapping.

Webhooks are not triggered for: - Visitor messages (messages with sender_type: "visitor"). - System messages (JOIN, LEAVE, etc.). - Chat sessions that were not created through UMI.

3.1 Message Webhook — `message_created`¶

Sent when an agent (human or AI) replies in a UMI chat session.

Payload¶

{
  "event_type": "message_created",
  "thread_id": "email-thread-12345",
  "chat_id": "a1b2c3d4-5678-90ab-cdef-123456789012",
  "message": {
    "id": "m1n2o3p4-5678-90ab-cdef-123456789012",
    "type": "msg",
    "chat_id": "a1b2c3d4-5678-90ab-cdef-123456789012",
    "room_id": "789e4567-e89b-12d3-a456-426614174111",
    "created_at": "2026-03-01T12:00:00.000Z",
    "sender_type": "user",
    "sender_id": "d4e5f6a7-1234-5678-abcd-ef0123456789",
    "sender_public_name": "Agent Smith",
    "sender_name": "Agent Smith",
    "sender_avatar": null,
    "message": "Your order #12345 has been shipped!",
    "is_encrypted": false,
    "is_edited": false,
    "sensitive_data_purged_at": null,
    "selected_reply_suggestion_id": null,
    "selected_reply_suggestion": null,
    "attachments": [],
    "attachment_template": null,
    "response_to_message_id": null,
    "response_to_attachment_id": null,
    "response_to_attachment": null,
    "response_to_action_id": null,
    "response_to_action": null,
    "response_text": null,
    "response_value": null
  },
  "messaging_channel": "email",
  "channel_config_id": "550e8400-e29b-41d4-a716-446655440000"
}

Top-level fields¶

Field	Type	Description
`event_type`	string	Always `"message_created"`.
`thread_id`	string	The external thread identifier from the original inbound message.
`chat_id`	UUID	Internal Giosg chat session ID.
`message`	object	Full serialized chat message (see below).
`messaging_channel`	string	Channel type (e.g., `"email"`, `"whatsapp"`).
`channel_config_id`	UUID	ID of the channel configuration.

`message` object fields¶

Field	Type	Description
`id`	UUID	Unique message identifier.
`type`	string	Message type. `"msg"` for normal messages.
`chat_id`	UUID	Chat session this message belongs to.
`room_id`	UUID	Room this message belongs to.
`created_at`	string (ISO 8601)	When the message was created.
`sender_type`	string	`"user"` for agent messages.
`sender_id`	string	UUID of the agent.
`sender_public_name`	string	Public display name (alias) of the agent.
`sender_name`	string	Full name of the agent.
`sender_avatar`	object or null	Avatar information, if set.
`message`	string	Text content of the message.
`is_encrypted`	boolean	Whether the message is encrypted.
`is_edited`	boolean	Whether the message has been edited.
`sensitive_data_purged_at`	string or null	When sensitive data was purged, if applicable.
`selected_reply_suggestion_id`	UUID or null	ID of the reply suggestion this message was based on, if any.
`selected_reply_suggestion`	object or null	Nested reply suggestion data, if any.
`attachments`	array	Message attachments (images, files, cards, etc.).
`attachment_template`	string or null	Attachment layout template type.
`response_to_message_id`	UUID or null	If this is a response to another message.
`response_to_attachment_id`	UUID or null	If this responds to a specific attachment.
`response_to_attachment`	object or null	Nested attachment data being responded to.
`response_to_action_id`	UUID or null	If this responds to a specific action button.
`response_to_action`	object or null	Nested action data being responded to.
`response_text`	string or null	User-facing text of the response.
`response_value`	string or null	Machine-readable value of the response.

See also documentation for Chat object and Message object for more details on the message structure and fields.

3.2 Reply Suggestion Webhook — `reply_suggestion_created`¶

Sent when an AI bot generates a reply suggestion for a visitor message in a UMI chat session.

Payload¶

{
  "event_type": "reply_suggestion_created",
  "thread_id": "email-thread-12345",
  "chat_id": "a1b2c3d4-5678-90ab-cdef-123456789012",
  "reply_suggestion": {
    "id": "rs-uuid-here",
    "created_by_user_id": "bot-user-uuid",
    "created_by_user": {
      "id": "bot-user-uuid",
      "first_name": "Bot",
      "last_name": "Assistant",
      "full_name": "Bot Assistant",
      "organization_id": "org-uuid",
      "avatar_id": null,
      "avatar": null,
      "is_bot": true,
      "is_staff": false
    },
    "updated_by_user_id": "bot-user-uuid",
    "updated_by_user": {
      "id": "bot-user-uuid",
      "first_name": "Bot",
      "last_name": "Assistant",
      "full_name": "Bot Assistant",
      "organization_id": "org-uuid",
      "avatar_id": null,
      "avatar": null,
      "is_bot": true,
      "is_staff": false
    },
    "chat_id": "a1b2c3d4-5678-90ab-cdef-123456789012",
    "message_id": "visitor-message-uuid",
    "room_id": "789e4567-e89b-12d3-a456-426614174111",
    "organization_id": "org-uuid",
    "created_at": "2026-03-01T12:01:00.000Z",
    "updated_at": "2026-03-01T12:01:00.000Z",
    "suggestion": "Your order #12345 was shipped yesterday and should arrive by Friday.",
    "relevancy_score": 0.95,
    "target_organization": null
  },
  "messaging_channel": "email",
  "channel_config_id": "550e8400-e29b-41d4-a716-446655440000"
}

Top-level fields¶

Field	Type	Description
`event_type`	string	Always `"reply_suggestion_created"`.
`thread_id`	string	The external thread identifier from the original inbound message.
`chat_id`	UUID	Internal Giosg chat session ID.
`reply_suggestion`	object	Full serialized reply suggestion (see below).
`messaging_channel`	string	Channel type (e.g., `"email"`, `"whatsapp"`).
`channel_config_id`	UUID	ID of the channel configuration.

`reply_suggestion` object fields¶

Field	Type	Description
`id`	UUID	Unique identifier for this reply suggestion.
`created_by_user_id`	UUID	UUID of the user (bot) that created this suggestion.
`created_by_user`	object	Nested user object.
`updated_by_user_id`	UUID	UUID of the user that last updated this suggestion.
`updated_by_user`	object	Same structure as `created_by_user`.
`chat_id`	UUID	Chat session this suggestion belongs to.
`message_id`	UUID	The visitor message this suggestion is a reply to.
`room_id`	UUID	Room this suggestion belongs to.
`organization_id`	UUID	Organization that owns this suggestion.
`created_at`	string (ISO 8601)	When the suggestion was created.
`updated_at`	string (ISO 8601)	When the suggestion was last updated.
`suggestion`	string	The suggested reply text.
`relevancy_score`	float or null	AI confidence score (0–1). `null` if not computed.
`target_organization`	string or null	Target organization, if applicable.

See also documentation for reply suggestions.

4. Session Types¶

Chat sessions created through UMI use the external session type:

Sessions do not automatically close on inactivity.
They support long-running conversations.
They must be closed explicitly via the Close Session endpoint, the close_session flag upon creation (ingesting old conversations), or through the normal Giosg agent UI.

5. Complete Integration Example¶

Below is a step-by-step example of a typical email integration.

Step 1 — Register your channel¶

curl -X POST \
  https://api.giosg.com/api/v5/orgs/YOUR_ORG_ID/unified_messaging \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Email Gateway",
    "messaging_channel": "email",
    "room_id": "YOUR_ROOM_UUID",
    "reply_webhook_url": "https://your-server.com/webhooks/giosg-replies"
  }'

Response:

{
  "id": "CONFIG_UUID",
  "name": "Support Email Gateway",
  "messaging_channel": "email",
  "organization_id": "YOUR_ORG_ID",
  "room_id": "YOUR_ROOM_UUID",
  "reply_webhook_url": "https://your-server.com/webhooks/giosg-replies",
  "max_retry_count": 3,
  "created_at": "2026-03-01T09:00:00.000Z",
  "modified_at": "2026-03-01T09:00:00.000Z"
}

Save the id (CONFIG_UUID) — you will need it for all subsequent calls.

Step 2 — Forward incoming messages to Giosg¶

When your external system receives a new message (e.g., a customer email), forward it to UMI:

curl -X POST \
  https://api.giosg.com/api/v5/orgs/YOUR_ORG_ID/unified_messaging/CONFIG_UUID/messages \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "body": "Hi, I need help with my order #12345",
        "thread_id": "support-ticket-67890",
        "sender_id": "customer@example.com",
        "message_id": "email-msg-001"
      }
    ],
    "variables": {
      "customer_name": "Jane Doe",
      "customer_email": "customer@example.com",
      "ticket_id": "TICKET-67890"
    }
  }'

Response:

{
  "chat_id": "CHAT_SESSION_UUID",
  "mapping_id": "MAPPING_UUID",
  "message_ids": ["MESSAGE_UUID"],
  "messages_created": 1,
  "is_new_session": true
}

The chat now appears in the Giosg agent UI in the configured room's waiting queue.

Step 3 — Customer sends a follow-up message¶

When the customer sends another message in the same thread, use the same thread_id. UMI will automatically route it to the existing chat session:

curl -X POST \
  https://api.giosg.com/api/v5/orgs/YOUR_ORG_ID/unified_messaging/CONFIG_UUID/messages \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "body": "My order number is #12345, placed on February 28th",
        "thread_id": "support-ticket-67890",
        "sender_id": "customer@example.com",
        "message_id": "email-msg-002"
      }
    ]
  }'

Response:

{
  "chat_id": "CHAT_SESSION_UUID",
  "mapping_id": "MAPPING_UUID",
  "message_ids": ["MESSAGE_UUID_2"],
  "messages_created": 1,
  "is_new_session": false
}

Note is_new_session: false — the message was added to the existing session.

Step 4 — Handle the agent-reply webhook¶

When an agent (human or AI) replies in the Giosg UI, your webhook endpoint receives:

{
  "event_type": "message_created",
  "thread_id": "support-ticket-67890",
  "chat_id": "CHAT_SESSION_UUID",
  "message": {
    "id": "REPLY_MESSAGE_UUID",
    "type": "msg",
    "chat_id": "CHAT_SESSION_UUID",
    "room_id": "YOUR_ROOM_UUID",
    "created_at": "2026-03-01T12:30:00.000Z",
    "sender_type": "user",
    "sender_id": "AGENT_UUID",
    "sender_public_name": "Agent Smith",
    "sender_name": "Agent Smith",
    "sender_avatar": null,
    "message": "Hi Jane! Your order #12345 was shipped yesterday. Tracking number: ABC123.",
    "is_encrypted": false,
    "is_edited": false,
    "sensitive_data_purged_at": null,
    "selected_reply_suggestion_id": null,
    "selected_reply_suggestion": null,
    "attachments": [],
    "attachment_template": null,
    "response_to_message_id": null,
    "response_to_attachment_id": null,
    "response_to_attachment": null,
    "response_to_action_id": null,
    "response_to_action": null,
    "response_text": null,
    "response_value": null
  },
  "messaging_channel": "email",
  "channel_config_id": "CONFIG_UUID"
}

Your system should:

Use thread_id to identify the external conversation.
Read message.message for the reply text and message.sender_public_name for the agent name.
Send the reply back to the customer through your external channel.
Respond with HTTP 200 to acknowledge receipt.

Step 5 — Handle the reply-suggestion webhook (optional)¶

If an AI bot generates a reply suggestion, your webhook endpoint receives:

{
  "event_type": "reply_suggestion_created",
  "thread_id": "support-ticket-67890",
  "chat_id": "CHAT_SESSION_UUID",
  "reply_suggestion": {
    "id": "SUGGESTION_UUID",
    "suggestion": "Your order #12345 was shipped yesterday and should arrive by Friday.",
    "relevancy_score": 0.92,
    "message_id": "VISITOR_MESSAGE_UUID",
    "chat_id": "CHAT_SESSION_UUID",
    "room_id": "YOUR_ROOM_UUID",
    "organization_id": "YOUR_ORG_ID",
    "created_by_user_id": "BOT_UUID",
    "created_by_user": { "id": "BOT_UUID", "full_name": "AI Assistant", "is_bot": true, "..." : "..." },
    "updated_by_user_id": "BOT_UUID",
    "updated_by_user": { "id": "BOT_UUID", "full_name": "AI Assistant", "is_bot": true, "..." : "..." },
    "created_at": "2026-03-01T12:25:00.000Z",
    "updated_at": "2026-03-01T12:25:00.000Z",
    "target_organization": null
  },
  "messaging_channel": "email",
  "channel_config_id": "CONFIG_UUID"
}

You can use the reply_suggestion.suggestion text to auto-reply or present it to a human agent for approval.

To send the approved suggestion as an actual reply, call the Message API with sender_type: "user" and reference the suggestion:

curl -X POST \
  https://api.giosg.com/api/v5/orgs/YOUR_ORG_ID/unified_messaging/CONFIG_UUID/messages \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "body": "Your order #12345 was shipped yesterday and should arrive by Friday.",
        "thread_id": "support-ticket-67890",
        "sender_id": "AGENT_OR_BOT_UUID",
        "message_id": "reply-msg-003",
        "sender_type": "user",
        "selected_reply_suggestion_id": "SUGGESTION_UUID"
      }
    ]
  }'

Step 6 — Close the session (optional)¶

When the conversation is resolved in your external system:

curl -X POST \
  https://api.giosg.com/api/v5/orgs/YOUR_ORG_ID/unified_messaging/CONFIG_UUID/close_session \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "thread_id": "support-ticket-67890"
  }'

Response:

{
  "chat_session_id": "CHAT_SESSION_UUID",
  "thread_id": "support-ticket-67890",
  "message": "Chat session closed successfully",
  "is_ended": true
}

Alternatively, you can pass "close_session": true in the Message API to close immediately after adding messages.

6. Sending Multiple Messages in One Batch¶

You can batch multiple messages into a single request. All messages must share the same thread_id:

curl -X POST \
  https://api.giosg.com/api/v5/orgs/YOUR_ORG_ID/unified_messaging/CONFIG_UUID/messages \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "body": "Hi, I have two questions.",
        "thread_id": "email-thread-99",
        "sender_id": "customer@shop.com",
        "message_id": "batch-msg-001"
      },
      {
        "body": "First: when will my order arrive?",
        "thread_id": "email-thread-99",
        "sender_id": "customer@shop.com",
        "message_id": "batch-msg-002"
      }
    ]
  }'

You can also mix visitor and user messages in a single batch:

curl -X POST \
  https://api.giosg.com/api/v5/orgs/YOUR_ORG_ID/unified_messaging/CONFIG_UUID/messages \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "body": "Customer question via email",
        "thread_id": "email-thread-100",
        "sender_id": "customer@shop.com",
        "message_id": "mix-msg-001",
        "sender_type": "visitor"
      },
      {
        "body": "Auto-reply: We received your message!",
        "thread_id": "email-thread-100",
        "sender_id": "AGENT_UUID",
        "message_id": "mix-msg-002",
        "sender_type": "user"
      }
    ],
    "skip_waiting_state": true
  }'

Unified Messaging Interface API

Unified Messaging Interface (UMI) — API Documentation¶

Overview¶

Why use UMI?¶

Authentication¶

1. Messaging Channel Configuration API¶

1.1 Register Messaging Channel¶

Request Payload¶

Response — 201 Created¶

Error Responses¶

1.2 List Messaging Channels¶

Query Parameters¶

Response — 200 OK¶

2. Message API¶

2.1 Create Messages¶

Request Payload¶

Top-level fields¶

Message object fields¶

Session lifecycle behavior¶

Response — 201 Created¶

Error Responses¶

2.2 Close Session¶

Request Payload¶

Response — 200 OK¶

Behavior notes¶

Error Responses¶

3. Webhooks (Giosg → Your System)¶

Webhook delivery¶

Webhook trigger conditions¶

3.1 Message Webhook — message_created¶

Payload¶

Top-level fields¶

message object fields¶

3.2 Reply Suggestion Webhook — reply_suggestion_created¶

Payload¶

Top-level fields¶

reply_suggestion object fields¶

4. Session Types¶

5. Complete Integration Example¶

Step 1 — Register your channel¶

Step 2 — Forward incoming messages to Giosg¶

Step 3 — Customer sends a follow-up message¶

Step 4 — Handle the agent-reply webhook¶

Step 5 — Handle the reply-suggestion webhook (optional)¶

Step 6 — Close the session (optional)¶

6. Sending Multiple Messages in One Batch¶

Response — `201 Created`¶

Response — `200 OK`¶

Response — `201 Created`¶

Response — `200 OK`¶

3.1 Message Webhook — `message_created`¶

`message` object fields¶

3.2 Reply Suggestion Webhook — `reply_suggestion_created`¶

`reply_suggestion` object fields¶