LogoLogo
AI TrainingUser Community
API Reference
API Reference
  • raia API
  • Users
  • Conversations
  • Prompts
  • Agents
  • Agent Files
  • Resource Usage Logs
  • Models
Powered by GitBook
On this page
Export as PDF

Conversations

PreviousUsersNextPrompts
CtrlK
  • GETGet conversations
  • POSTCreate a new conversation
  • DELETEDelete all user conversations in current agent
  • GETGet conversation by ID
  • PUTUpdate conversation
  • POSTStart a new conversation
  • GETGet conversation messages
  • POSTSend a message to an agent

Get conversations

get

Fetches a conversations by agent API key. The response includes the conversation details.

Authorizations
Query parameters
pagenumberOptional

Page number

pageSizenumberOptional

Page size

orderBystring · enumOptional

Order by

Possible values:
orderDirectionstring · enumOptional

Order direction

Possible values:
withFeedbacksOnlybooleanOptional

If true, returns conversations with at least one feedback

Responses
200

Successfully received conversations.

application/json
403

Invalid API key or secret key. Ensure that you are using a valid authentication key.

application/json
500

Unexpected error occurred while processing the request. Please try again later.

application/json
get
GET /external/conversations HTTP/1.1
Host: api.raia2.com
Agent-Secret-Key: YOUR_API_KEY
Accept: */*
{
  "currentPage": 1,
  "pageSize": 1,
  "totalItems": 1,
  "totalPages": 1,
  "hasNextPage": true,
  "hasPreviousPage": true,
  "data": [
    {
      "id": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
      "conversationUserId": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
      "title": "Conversation Title",
      "score": 4,
      "summary": "This is a summary of the conversation.",
      "threadId": "thread_h435hi34h5i43i5",
      "metadata": {
        "customData": {
          "key1": "value1",
          "key2": "value2"
        }
      },
      "aiCallId": "call_h435hi34h5i43i5",
      "mode": "manual",
      "feedbacks": [
        {
          "id": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
          "voteType": "down",
          "question": "text",
          "answer": "text",
          "comment": "text"
        }
      ]
    }
  ]
}

Create a new conversation

post

Creates a new conversation . The response includes the conversation ID.

Authorizations
Body
conversationUserIdstringRequired

Conversation user ID

Example: 5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b
titlestring · max: 255Optional

Conversation title

Example: New Conversation Title
contextstring · max: 256000Optional

Conversation context

Example: New conversation context
customDataobjectOptional

Conversation custom data

Example: {"key1":"value1","key2":"value2"}
Responses
201

Successfully created a new conversation.

application/json
403

Invalid API key or secret key. Ensure that you are using a valid authentication key.

application/json
500

Unexpected error occurred while processing the request. Please try again later.

application/json
post
POST /external/conversations HTTP/1.1
Host: api.raia2.com
Agent-Secret-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 178

{
  "conversationUserId": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
  "title": "New Conversation Title",
  "context": "New conversation context",
  "customData": {
    "key1": "value1",
    "key2": "value2"
  }
}
{
  "id": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
  "conversationUserId": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
  "title": "Conversation Title",
  "score": 4,
  "summary": "This is a summary of the conversation.",
  "threadId": "thread_h435hi34h5i43i5",
  "metadata": {
    "customData": {
      "key1": "value1",
      "key2": "value2"
    }
  },
  "aiCallId": "call_h435hi34h5i43i5",
  "mode": "manual"
}

Delete all user conversations in current agent

delete

Delete all conversations associated with specified user in current agent.

Authorizations
Body
conversationUserIdstringRequired

Conversation user ID

Example: 5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b
Responses
204

Successfully delete all user conversations in current agent.

403

Invalid API key or secret key. Ensure that you are using a valid authentication key.

application/json
500

Unexpected error occurred while processing the request. Please try again later.

application/json
delete
DELETE /external/conversations HTTP/1.1
Host: api.raia2.com
Agent-Secret-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 61

{
  "conversationUserId": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b"
}

No content

Get conversation by ID

get

Fetches a conversation by its unique ID. The response includes the conversation details.

Authorizations
Path parameters
idstringRequired

The ID of the conversation to retrieve.

Example: 5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b
Responses
200

Successfully retrieved the conversation.

application/json
403

Invalid API key or secret key. Ensure that you are using a valid authentication key.

application/json
404

Conversation not found.

application/json
500

Unexpected error occurred while processing the request. Please try again later.

application/json
get
GET /external/conversations/{id} HTTP/1.1
Host: api.raia2.com
Agent-Secret-Key: YOUR_API_KEY
Accept: */*
{
  "id": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
  "conversationUserId": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
  "title": "Conversation Title",
  "score": 4,
  "summary": "This is a summary of the conversation.",
  "threadId": "thread_h435hi34h5i43i5",
  "metadata": {
    "customData": {
      "key1": "value1",
      "key2": "value2"
    }
  },
  "aiCallId": "call_h435hi34h5i43i5",
  "mode": "manual"
}

Update conversation

put

Updates an existing conversation by ID. Returns the updated conversation.

Authorizations
Path parameters
idstringRequired

The ID of the conversation to update.

Example: 5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b
Body
titlestring · max: 255Optional

Conversation title

Example: Updated Conversation Title
contextstring · max: 256000Optional

Conversation context

Example: Updated conversation context
statusstring · enumOptional

Conversation status

Example: activePossible values:
modestring · enumOptional

Conversation mode

Example: aiPossible values:
Responses
200

Successfully updated the conversation.

application/json
403

Invalid API key or secret key. Ensure that you are using a valid authentication key.

application/json
404

Conversation not found.

application/json
500

Unexpected error occurred while processing the request. Please try again later.

application/json
put
PUT /external/conversations/{id} HTTP/1.1
Host: api.raia2.com
Agent-Secret-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 109

{
  "title": "Updated Conversation Title",
  "context": "Updated conversation context",
  "status": "active",
  "mode": "ai"
}
{
  "id": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
  "conversationUserId": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
  "title": "Conversation Title",
  "score": 4,
  "summary": "This is a summary of the conversation.",
  "threadId": "thread_h435hi34h5i43i5",
  "metadata": {
    "customData": {
      "key1": "value1",
      "key2": "value2"
    }
  },
  "aiCallId": "call_h435hi34h5i43i5",
  "mode": "manual"
}

Start a new conversation

post

Start a new conversation using either an email, SMS or voice as the communication method. The response includes the conversation ID.

Authorizations
Body
one ofOptional
or
or
Responses
201

Successfully start a new conversation.

application/json
403

Invalid API key or secret key. Ensure that you are using a valid authentication key.

application/json
500

Unexpected error occurred while processing the request. Please try again later.

application/json
post
POST /external/conversations/start HTTP/1.1
Host: api.raia2.com
Agent-Secret-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 392

{
  "firstName": "John",
  "lastName": "Doe",
  "context": "Support",
  "conversationContext": "Support",
  "source": "webchat",
  "fkId": "123456",
  "fkUserId": "123456",
  "customData": {
    "key1": "value1",
    "key2": "value2"
  },
  "channel": "email",
  "email": "[email protected]",
  "emailSubject": "New Conversation",
  "emailIntroduction": "New Conversation",
  "includeSignatureInEmail": false,
  "phoneNumber": "+1234567890",
  "resetConversation": false
}
{
  "conversationId": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b"
}

Get conversation messages

get

Fetches all messages associated with a specific conversation ID.

Authorizations
Path parameters
idstringRequired

The ID of the conversation to retrieve messages for.

Example: 5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b
Query parameters
shouldIncludeFeedbacksbooleanOptional

If true, returns conversation messages with feedbacks

orderDirectionstring · enumOptional

Message created at order direction. Default: ASC

Possible values:
Responses
200

Successfully retrieved conversation messages.

application/json
403

Invalid API key or secret key. Ensure that you are using a valid authentication key.

application/json
500

Unexpected error occurred while processing the request. Please try again later.

application/json
get
GET /external/conversations/{id}/messages HTTP/1.1
Host: api.raia2.com
Agent-Secret-Key: YOUR_API_KEY
Accept: */*
{
  "messages": [
    {
      "id": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
      "message": "Hello, how can I help you?",
      "rawMessage": "Raw message example",
      "conversationId": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
      "senderRole": "conversation_user",
      "conversationMessageId": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
      "source": "api",
      "createdAt": "2022-01-01T00:00:00.000Z",
      "conversationMessageFeedbacks": [
        {
          "id": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
          "voteType": "down",
          "question": "text",
          "answer": "text",
          "comment": "text"
        }
      ]
    }
  ]
}

Send a message to an agent

post

Send a new message to an agent using conversationId.

Authorizations
Path parameters
idstringRequired

The ID of the conversation to send a message to.

Example: 5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b
Body
messagestringRequired

The message that the user sends to the AI agent

Example: How does quantum entanglement work?
contextstringOptional

Context of the message

Example: User is asking about quantum physics.
Responses
201

Response from the agent.

application/json
403

Invalid API key or secret key. Ensure that you are using a valid authentication key.

application/json
500

Unexpected error occurred while processing the request. Please try again later.

application/json
post
POST /external/conversations/{id}/messages HTTP/1.1
Host: api.raia2.com
Agent-Secret-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 99

{
  "message": "How does quantum entanglement work?",
  "context": "User is asking about quantum physics."
}
{
  "id": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
  "message": "Hello, how can I help you?",
  "rawMessage": "Raw message example",
  "conversationId": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
  "senderRole": "conversation_user",
  "conversationMessageId": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
  "source": "api",
  "createdAt": "2022-01-01T00:00:00.000Z",
  "conversationMessageFeedbacks": [
    {
      "id": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
      "voteType": "down",
      "question": "text",
      "answer": "text",
      "comment": "text"
    }
  ]
}