Messages

Messages are individual communications within a conversation. Each message can contain text or media content and maintains metadata about its creation and status.

Send Message

Send a new message in a conversation.

Endpoint: POST /messages
Authentication: API Key Required

Headers

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

Message Types

The content_type field determines the message format and required fields:

TEXT ("content_type": "text")
- Basic text messages
- Requires content field
- No file handling needed
MEDIA (audio/*, image/*, application/pdf, etc.)
- Used for file attachments
- Requires filename field
- Must obtain pre-signed URL before upload
- Supports various formats (audio, image, PDF, XLSX, CSV)
- More detail below Media Handling

Request Body

Field	Type	Required	Description
conversation	string	Yes	ID of the conversation
content	string	Conditional	Message text (required for text messages)
content_type	string	Yes	Message format (see Supported Types)
filename	string	Conditional	File path/name (required for media)
metadata	object	No	Custom message data
channel	string	No	Defaults to “api”

Example: Text Message

{
  "conversation": "550e8400e29b41d4a716446655440000",
  "content": "Hello world!",
  "content_type": "text",
  "metadata": {
    // Optional metadata
  }
}

Example: Media Message

{
  "conversation": "550e8400e29b41d4a716446655440000",
  "filename": "20240321_120000_report.pdf",
  "content_type": "application/pdf",
  "metadata": {
    // Optional metadata
  }
}

Response

{
  "id": "550e8400e29b41d4a716446655440000",
  "conversation": "550e8400e29b41d4a716446655440000",
  "content": "Hello world!",
  "content_type": "text",
  "channel": "api",
  "type": "USER_INPUT",
  "status": "received",
  "metadata": {
    // Additional metadata
  },
  "created_at": "2024-03-21T10:00:00Z",
  "updated_at": "2024-03-21T10:00:00Z"
}

Supported Content Types

Type	Content Type	Required Fields	Max Size	Description
Text	text	content	4KB	Plain text messages
Audio	audio/*	filename	10MB	Voice messages, audio files
Image	image/*	filename	5MB	Photos and images
PDF	application/pdf	filename	10MB	PDF documents
Excel	application/xlsx	filename	10MB	Excel spreadsheets
CSV	text/csv	filename	5MB	CSV data files

Status Codes

200: Message sent successfully
400: Validation error
401: Invalid or missing API key
422: Missing organization ID
500: Server error

Example Request

curl 'https://beta-api.gaife.com/developer/api/messages' \
  -H 'Authorization: Bearer {{API_KEY}}' \
  -H 'Content-Type: application/json' \
  --data-raw '{"conversation":"550e8400e29b41d4a716446655440000","content":"Hello world!","content_type":"text"}'

Notes

File Uploads:
- Obtain pre-signed URL before uploading media
- Use appropriate content type headers
- Respect file size limits
Message Processing:
- Messages are processed asynchronously
- Check message status for delivery confirmation
- All timestamps are in UTC
Metadata Usage:
- Use metadata for custom tracking
- Metadata must be valid JSON
- Maximum metadata size: 4KB
Rate Limits:
- 100 messages per minute per organization
- Larger limits available for enterprise plans

Media Handling

For sending media messages (images, audio, PDFs, etc.), you’ll need to follow a three-step process:

Step 1: Get Pre-signed URL

Endpoint: POST /media/presigned-url Headers:

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

Request Body:

{
  "file_name": "report.pdf",
  "file_type": "application/pdf"
}

Response:

{
  // The URL to upload the file
  "presigned_url": "https://s3.amazonaws.com/bucket/...",
  // The file name will be used to send the message
  "file_name": "20240321_120000_report.pdf"
}

Curl Example:

curl -X POST 'https://beta-api.gaife.com/developer/api/media/presigned-url' \
  -H 'Authorization: Bearer {{API_KEY}}' \
  -H 'Content-Type: application/json' \
  -d '{
    "file_name": "report.pdf",
    "file_type": "application/pdf"
}'

Step 2: Upload File

Use the pre-signed URL to upload your file:

curl --location --request PUT "${PRESIGNED_URL}" \ # The URL received from Step 1
    --header "Content-Type: application/octet-stream" \
    --data-binary "@/path/to/your/file"

Note: Replace ${PRESIGNED_URL} with the URL received from Step 1, and adjust the file path to your local file location.

Step 3: Send Message

After successful upload, send the message:

{
  "conversation": "550e8400e29b41d4a716446655440000",
  // Use the file name received from Step 1
  "filename": "20240321_120000_report.pdf",
  "content_type": "application/pdf",
  "metadata": {
    // Optional metadata
  }
}

Curl Example:

curl --location 'https://beta-api.gaife.com/developer/api/messages' \
    --header 'Authorization: Bearer {{API_KEY}}' \
    --header 'Content-Type: application/json' \
    --data '{
        "conversation": "550e8400e29b41d4a716446655440000",
        "content_type": "image/jpeg",
        "filename": "20240321_120000_image.jpg",
    }'

Supported File Types

File Type	Content Type	Storage Folder
Audio	audio/*	audio/
Image	image/*	images/
PDF	application/pdf	pdfs/
Excel	application/xlsx	xlsx/
CSV	text/csv	csv/

Complete Example

import requests

# 1. Get pre-signed URL
presigned_response = requests.post(
    'https://api.example.com/media/presigned-url',
    headers={
        'Authorization': 'Bearer your_api_key',
        'Content-Type': 'application/json'
    },
    json={
        'file_name': 'report.pdf',
        'file_type': 'application/pdf'
    }
)
presigned_data = presigned_response.json()

# 2. Upload file using pre-signed URL
with open('report.pdf', 'rb') as f:
    requests.put(
        presigned_data['presigned_url'],
        data=f,
        headers={'Content-Type': 'application/pdf'}
    )

# 3. Send message with file reference
message_response = requests.post(
    'https://api.example.com/messages',
    headers={
        'Authorization': 'Bearer your_api_key',
        'Content-Type': 'application/json'
    },
    json={
        'conversation': '550e8400e29b41d4a716446655440000',
        'filename': presigned_data['file_name'],
        'content_type': 'application/pdf'
    }
)

Media Upload Notes

File Naming:
- Uploaded files are automatically prefixed with timestamp
- Format: YYYYMMDD_HHMMSS_original_filename
Storage Organization:
- Files are stored in type-specific folders
- Each organization has its own directory
- Maintains clean separation of different file types
Limitations:
- Text files are not supported for pre-signed URLs
- Pre-signed URLs expire after 15 minutes
- File type must match the declared content type
Error Cases:
- 422: Missing organization ID
- 400: Invalid file type or unsupported operation
- 500: Server error during URL generation

Message Metadata

The metadata field in messages serves several critical functions:

File Storage Information
- Tracks file storage details for system generated files
- Used when system generates a file response
- System automatically processes the file:
  - Extracts bucket and path information
  - Transfers file to conversation media bucket
  - Updates message with standardized S3 URI
- Supports both HTTPS and S3 protocol URLs
- File access requires proper authentication
- Example message metadata:
  // Original metadata from AI Engine { "metadata": { "from_s3": true, "output": { "s3_url": "https://bucket.s3.amazonaws.com/file.pdf", "output_type": "application/pdf" } } }

Workflow Instance Status

{
  "metadata": {
    "workflow_instance_id": "789",
    "workflow_instance_status": "RUNNING"
  }
}

The metadata tracks workflow execution state through the workflow_instance_status field: Available Status Values

Status	Description
`RUNNING`	Workflow is actively executing tasks
`PAUSED`	Workflow execution has been temporarily suspended
`COMPLETED`	All tasks have successfully finished
`FAILED`	Workflow stopped due to an error
`CANCELLED`	Workflow was manually cancelled by user
`TERMINATED`	Workflow stopped due to system intervention

Example Status Updates === “Initial workflow start”

{
    "metadata": {
        "workflow_instance_id": "789",
        "workflow_instance_status": "RUNNING"
    }
}

=== “Workflow paused for user input”

{
    "metadata": {
        "workflow_instance_id": "789",
        "workflow_instance_status": "PAUSED"
    }
}

=== “Workflow completion”

{
    "metadata": {
        "workflow_instance_id": "789",
        "workflow_instance_status": "COMPLETED"
    }
}

Status Transitions

RUNNING → Any status
PAUSED → RUNNING, CANCELLED, TERMINATED
COMPLETED (Terminal state)
FAILED (Terminal state)
CANCELLED (Terminal state)
TERMINATED (Terminal state)

Important Notes

Status updates are real-time
Terminal states cannot transition to other states
Each status update includes timestamp information
Status changes may trigger notifications or webhook events
Historical status changes are preserved in workflow logs

Ticket Integration
{ "ticket_id": "123", "task_instance_status": "EXECUTED" }
The metadata contains ticket information that automatically manages support ticket lifecycles: Status Management
- Ticket status is automatically updated based on task instance status:
  ERRORED, CANCELLED, REJECTED → CLOSED EXECUTED → RESOLVED
- Updates are handled atomically to prevent race conditions
- Status changes are tracked in ticket history
Ticket Fields Important ticket information tracked:
{ "workflow_instance_id": "789", "failed_task_id": "456", "exception_message": "Error details", "workflow_name": "Document Processing", "task_name": "PDF Generation", "workflow_progress": 75.5, "conversation_id": "conv_123" }
Example Metadata Usage
{ "metadata": { "ticket_id": "123", "task_instance_status": "EXECUTED", "workflow_instance_id": "789", "task_name": "Document Processing", "workflow_progress": 85.5 } }
Notification System When tickets are created or updated:
- Assignees receive email notifications
- Notifications include:
  - Ticket ID
  - Task name and description
  - Workflow name
  - Exception details (if any)
  - Assignment details
Important Notes
- Ticket updates are processed atomically using database transactions
- Missing ticket IDs are safely ignored
- Status updates are immediate and automatic
- All ticket activities are logged for audit purposes

Example Message with Complex Metadata

{
  "conversation": "550e8400e29b41d4a716446655440000",
  "content": "Processing your document...",
  "content_type": "text",
  "metadata": {
    "from_s3": true,
    "output": {
      "s3_url": "s3://bucket/org123/documents/20240321_120000_report.pdf",
      "output_type": "application/pdf"
    },
    "workflow_instance_id": "789",
    "workflow_instance_status": "RUNNING",
    "ticket_id": "244",
    "task_instance_status": "EXECUTED"
  }
}

Chat

WhatsApp

Send Message

Headers

Message Types

Request Body

Example: Text Message

Example: Media Message

Response

Supported Content Types

Status Codes

Example Request

Notes

Media Handling

Step 1: Get Pre-signed URL

Step 2: Upload File

Step 3: Send Message

Supported File Types

Complete Example

Media Upload Notes

Message Metadata

Example Message with Complex Metadata

​Send Message

​Headers

​Message Types

​Request Body

​Example: Text Message

​Example: Media Message

​Response

​Supported Content Types

​Status Codes

​Example Request

​Notes

​Media Handling

​Step 1: Get Pre-signed URL

​Step 2: Upload File

​Step 3: Send Message

​Supported File Types

​Complete Example

​Media Upload Notes

​Message Metadata

​Example Message with Complex Metadata

Send Message

Headers

Message Types

Request Body

Example: Text Message

Example: Media Message

Response

Supported Content Types

Status Codes

Example Request

Notes

Media Handling

Step 1: Get Pre-signed URL

Step 2: Upload File

Step 3: Send Message

Supported File Types

Complete Example

Media Upload Notes

Message Metadata

Example Message with Complex Metadata