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
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
}
}
{
"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
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'
}
)
-
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
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
{
"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"
}
}
Responses are generated using AI and may contain mistakes.