Skip to main content
POST
/
api
/
public
/
thread
/
{id}
/
messages
Send Message
curl --request POST \
  --url https://api.nexusgpt.io/api/public/thread/{id}/messages \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '
{
  "content": "<string>"
}
'
{
  "success": true
}

​
Send Message

Sends a message to an existing chat session. The AI agent will process the message and generate an appropriate response based on the conversation context.

​
Endpoint

POST https://api.nexusgpt.io/api/public/thread/{id}/messages

​
Authentication

​
api-key
string
required
Your Nexus API key for authentication

​
Path Parameters

​
id
string
required
The session ID obtained from creating a session. This identifies which conversation thread to send the message to.

​
Request Body

​
content
string
required
The message content to send to the AI agent. Maximum length: 4000 characters.
{
  "success": true
}

​
Response Fields

​
success
boolean
required
Indicates whether the message was successfully sent and queued for processing

​
Example Usage

curl -X POST https://api.nexusgpt.io/api/public/thread/550e8400-e29b-41d4-a716-446655440000/messages \
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_API_KEY" \
  -d '{"content": "Can you help me track my order #12345?"}'

​
Message Processing

​
How It Works

  1. Message Receipt: Your message is received and validated
  2. Context Loading: Previous conversation history is loaded
  3. AI Processing: The agent processes your message with full context
  4. Response Generation: A contextual response is generated
  5. Storage: Both messages are stored in the conversation thread

​
Response Time

  • Typical response time: 1-3 seconds
  • Complex queries may take longer
  • Use polling to retrieve responses

​
Common Patterns

​
1. Send and Wait Pattern

async function sendAndWaitForResponse(sessionId, message) {
  // Send the message
  await sendMessage(sessionId, message);
  
  // Poll for response (with exponential backoff)
  let attempts = 0;
  while (attempts < 5) {
    await new Promise(resolve => setTimeout(resolve, 1000 * Math.pow(1.5, attempts)));
    
    const messages = await getMessages(sessionId, { limit: 2, order: 'desc' });
    const latestMessage = messages[0];
    
    if (latestMessage.type === 'assistant' && latestMessage.createdAt > sentTime) {
      return latestMessage;
    }
    
    attempts++;
  }
  
  throw new Error('Timeout waiting for response');
}

​
2. Conversation Flow

async function handleConversation(sessionId) {
  // Initial greeting
  await sendMessage(sessionId, "Hello!");
  
  // Follow-up with context
  await sendMessage(sessionId, "I need help with order #12345");
  
  // Provide additional details
  await sendMessage(sessionId, "It was supposed to arrive yesterday");
}

​
3. Structured Queries

// Send structured information
const orderQuery = {
  intent: "track_order",
  orderId: "12345",
  email: "customer@example.com"
};

await sendMessage(sessionId, JSON.stringify(orderQuery));

​
Error Responses

{
  "statusCode": 401,
  "message": "Invalid API key",
  "error": "Unauthorized"
}

​
Best Practices

  • Keep messages concise and clear
  • Use proper punctuation and grammar
  • Break complex queries into multiple messages
  • Avoid sending multiple messages too quickly
  • Send related messages in the same session
  • Create new sessions for unrelated topics
  • Include relevant details in your messages
  • Reference previous messages when needed
  • Implement retry logic for failed sends
  • Handle session expiration gracefully
  • Validate message content before sending
  • Log failed messages for debugging
  • Batch related information in single messages
  • Use appropriate polling intervals
  • Implement client-side rate limiting
  • Cache session IDs for reuse

​
Limitations

  • Message Length: Maximum 4000 characters per message
  • Rate Limits: 60 messages per minute per API key
  • Session Limits: Messages must be sent to active sessions
  • Content Policy: Messages must comply with usage policies