Skip to main content
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:
  1. DEFAULT ("usecase": "DEFAULT")
    • Standard conversation, chat with the GAIFE system
    • Used for general messaging purposes
  2. 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

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