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:

  1. TEXT ("content_type": "text")

    • Basic text messages
    • Requires content field
    • No file handling needed
  2. 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

FieldTypeRequiredDescription
conversationstringYesID of the conversation
contentstringConditionalMessage text (required for text messages)
content_typestringYesMessage format (see Supported Types)
filenamestringConditionalFile path/name (required for media)
metadataobjectNoCustom message data
channelstringNoDefaults 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

TypeContent TypeRequired FieldsMax SizeDescription
Texttextcontent4KBPlain text messages
Audioaudio/*filename10MBVoice messages, audio files
Imageimage/*filename5MBPhotos and images
PDFapplication/pdffilename10MBPDF documents
Excelapplication/xlsxfilename10MBExcel spreadsheets
CSVtext/csvfilename5MBCSV 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

  1. File Uploads:

    • Obtain pre-signed URL before uploading media
    • Use appropriate content type headers
    • Respect file size limits
  2. Message Processing:

    • Messages are processed asynchronously
    • Check message status for delivery confirmation
    • All timestamps are in UTC
  3. Metadata Usage:

    • Use metadata for custom tracking
    • Metadata must be valid JSON
    • Maximum metadata size: 4KB
  4. 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 TypeContent TypeStorage Folder
Audioaudio/*audio/
Imageimage/*images/
PDFapplication/pdfpdfs/
Excelapplication/xlsxxlsx/
CSVtext/csvcsv/

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

  1. File Naming:

    • Uploaded files are automatically prefixed with timestamp
    • Format: YYYYMMDD_HHMMSS_original_filename
  2. Storage Organization:

    • Files are stored in type-specific folders
    • Each organization has its own directory
    • Maintains clean separation of different file types
  3. 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
  4. 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:

  1. 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"
              }
          }
      }
      
  2. 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

    StatusDescription
    RUNNINGWorkflow is actively executing tasks
    PAUSEDWorkflow execution has been temporarily suspended
    COMPLETEDAll tasks have successfully finished
    FAILEDWorkflow stopped due to an error
    CANCELLEDWorkflow was manually cancelled by user
    TERMINATEDWorkflow 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
    • PAUSEDRUNNING, 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
  3. 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"
    }
}