Conversations

Conversations represent chat sessions in the system. Each conversation is associated with a workflow and can contain multiple messages.

Base URL

All API endpoints are prefixed with the following base URL:

https://beta-api.gaife.com/developer/api

Create a Conversation

Create a new conversation instance.

Endpoint: POST /conversations
Authentication: API Key Required

Headers

Authorization: Bearer {{API_KEY}}
Content-Type: application/json

Conversation Usecases

The usecase field determines the conversation’s purpose and behavior:

DEFAULT ("usecase": "DEFAULT")
- Standard conversation, chat with the GAIFE system
- Used for general messaging purposes
WORKFLOW_EXECUTION ("usecase": "WORKFLOW_EXECUTION")
- Used when executing an existing workflow
- Automatically sets metadata with workflow_id from config
- Enables workflow-specific message processing

!!! info Optionally, configure a callback_url in config to receive a webhook/callback on every message of conversation.

Request Body

{
  "channel": "API",
  "usecase": "WORKFLOW_EXECUTION", // One of: DEFAULT, WORKFLOW_EXECUTION
  "config": {
    "workflow_id": "string", // Required, the ID of the workflow to execute
    "callback_url": "string" // To receive a webhook on every message of conversation
    // Additional configuration
  },
  "metadata": {
    // Optional custom data
  },
  "team_id": "integer" // Optional
}

Response

{
  "id": "string" // conversation ID without hyphens
}

Example Usecases Request Body

=== “Workflow Execution”

{
    "channel": "API",
    "usecase": "WORKFLOW_EXECUTION",
    "config": {
        "workflow_id": "123",
        "callback_url": "https://example.com/webhook"
    }
}

=== “Default”

{
    "channel": "API",
    "usecase": "DEFAULT",
    "config": {
        "callback_url": "https://example.com/webhook"
    }
}

Notes

For WORKFLOW_EXECUTION, the metadata will automatically include the workflow_id from config
The DEFAULT usecase provides the most flexibility for custom implementations
All usecases support custom metadata for additional context
The channel field is used to specify the communication channel, currently only API is supported
To receive a webhook on every message of conversation, configure a callback_url in config

Example Request

curl 'https://beta-api.gaife.com/developer/api/conversations' \
  -H 'Authorization: Bearer {{API_KEY}}' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "channel":"API",
    "usecase":"WORKFLOW_EXECUTION",
    "config":{
      "workflow_id":"84",
      "callback_url":"https://example.com/webhook"
    }
  }'

Example Response

{
  "id": "550e8400e29b41d4a716446655440000"
}

Status Codes

201: Conversation created successfully
400: Invalid request data
401: Invalid or missing API key
500: Server error

Get Conversation Messages

Retrieve all messages in a conversation.

Endpoint: GET /conversations/{conversation_id}/messages
Authentication: Required

Path Parameters

conversation_id: The ID of the conversation

Example Request

curl 'https://beta-api.gaife.com/developer/api/conversations/550e8400e29b41d4a716446655440000/messages' \
  -H 'Authorization: Bearer {{API_KEY}}' \
  -H 'Content-Type: application/json'

Response

Messages are returned in chronological order, from newest to oldest.

[
  {
    "id": "string",
    "conversation_id": "string",
    "content": "string",
    "content_type": "TEXT", // One of: TEXT, IMAGE, VIDEO, AUDIO, etc.
    "filename": "string", // Optional, present for media messages
    "type": "USER_INPUT", // Message type
    "channel": "string", // Communication channel
    "status": "RECEIVED", // Message status
    "metadata": {
      "key": "value" // Optional custom metadata
    },
    "created_by": "string",
    "created_at": "datetime",
    "updated_at": "datetime"
  }
]

Status Codes

200: Success
404: Conversation not found
500: Server error

Notes

Content Types:
- TEXT: Regular text messages
- IMAGE: Image files
- VIDEO: Video files
- AUDIO: Audio files
Message Types:
- USER_INPUT: Messages from users
- Other types as per your MessageType choices
Message Status:
- RECEIVED: Message has been received
- Other statuses as per your MessageStatus choices
Response Fields:
- id: Unique message identifier
- content: Message content/text
- filename: Present only for media messages
- metadata: Optional JSON object for additional data

Chat

WhatsApp

Base URL

Create a Conversation

Headers

Conversation Usecases

Request Body

Response

Example Usecases Request Body

Notes

Example Request

Example Response

Status Codes

Get Conversation Messages

Path Parameters

Example Request

Response

Status Codes

Notes

​Base URL

​Create a Conversation

​Headers

​Conversation Usecases

​Request Body

​Response

​Example Usecases Request Body

​Notes

​Example Request

​Example Response

​Status Codes

​Get Conversation Messages

​Path Parameters

​Example Request

​Response

​Status Codes

​Notes

Base URL

Create a Conversation

Headers

Conversation Usecases

Request Body

Response

Example Usecases Request Body

Notes

Example Request

Example Response

Status Codes

Get Conversation Messages

Path Parameters

Example Request

Response

Status Codes

Notes