Conversations

Get conversations

get

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

Authorizations

Agent-Secret-Key

Agent-Secret-KeystringRequired

Custom authentication header

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

/external/conversations

HTTPcURLJavaScriptPython

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.",
      "aiConversationId": "conv_h435hi34h5i43i5sdfdfs",
      "metadata": {
        "customData": {
          "key1": "value1",
          "key2": "value2"
        }
      },
      "aiCallId": "call_h435hi34h5i43i5",
      "mode": "manual",
      "conversationStateId": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
      "feedbacks": [
        {
          "id": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
          "voteType": "down",
          "question": "text",
          "answer": "text",
          "comment": "text",
          "userEmail": "text",
          "createdAt": "2023-01-01T00:00:00.000Z",
          "updatedAt": "2023-01-01T00:00:00.000Z"
        }
      ]
    }
  ]
}

Create a new conversation

post

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

Authorizations

Agent-Secret-Key

Agent-Secret-KeystringRequired

Custom authentication header

Body

application/json

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"}

conversationStateIdstringOptional

Conversation state ID

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

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

/external/conversations

HTTPcURLJavaScriptPython

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

{
  "conversationUserId": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
  "title": "New Conversation Title",
  "context": "New conversation context",
  "customData": {
    "key1": "value1",
    "key2": "value2"
  },
  "conversationStateId": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b"
}

{
  "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.",
  "aiConversationId": "conv_h435hi34h5i43i5sdfdfs",
  "metadata": {
    "customData": {
      "key1": "value1",
      "key2": "value2"
    }
  },
  "aiCallId": "call_h435hi34h5i43i5",
  "mode": "manual",
  "conversationStateId": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b"
}

Delete all user conversations in current agent

delete

Delete all conversations associated with specified user in current agent.

Authorizations

Agent-Secret-Key

Agent-Secret-KeystringRequired

Custom authentication header

Body

application/json

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

/external/conversations

HTTPcURLJavaScriptPython

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 states

get

Fetches all available conversation states by agent API key.

Authorizations

Agent-Secret-Key

Agent-Secret-KeystringRequired

Custom authentication header

Responses

200

Successfully retrieved conversation states.

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

/external/conversations/states

HTTPcURLJavaScriptPython

GET /external/conversations/states HTTP/1.1
Host: api.raia2.com
Agent-Secret-Key: YOUR_API_KEY
Accept: */*

{
  "id": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
  "name": "text",
  "description": "text",
  "color": "text",
  "isPersistent": true,
  "createdAt": "2023-01-01T00:00:00.000Z",
  "updatedAt": "2023-01-01T00:00:00.000Z"
}

Get conversation by ID

get

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

Authorizations

Agent-Secret-Key

Agent-Secret-KeystringRequired

Custom authentication header

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

/external/conversations/{id}

HTTPcURLJavaScriptPython

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.",
  "aiConversationId": "conv_h435hi34h5i43i5sdfdfs",
  "metadata": {
    "customData": {
      "key1": "value1",
      "key2": "value2"
    }
  },
  "aiCallId": "call_h435hi34h5i43i5",
  "mode": "manual",
  "conversationStateId": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
  "feedbacks": [
    {
      "id": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
      "voteType": "down",
      "question": "text",
      "answer": "text",
      "comment": "text",
      "userEmail": "text",
      "createdAt": "2023-01-01T00:00:00.000Z",
      "updatedAt": "2023-01-01T00:00:00.000Z"
    }
  ]
}

Update conversation

put

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

Authorizations

Agent-Secret-Key

Agent-Secret-KeystringRequired

Custom authentication header

Path parameters

idstringRequired

The ID of the conversation to update.

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

Body

application/json

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:

conversationStateIdstringOptional

Conversation state ID

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

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

/external/conversations/{id}

HTTPcURLJavaScriptPython

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

{
  "title": "Updated Conversation Title",
  "context": "Updated conversation context",
  "status": "active",
  "mode": "ai",
  "conversationStateId": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b"
}

{
  "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.",
  "aiConversationId": "conv_h435hi34h5i43i5sdfdfs",
  "metadata": {
    "customData": {
      "key1": "value1",
      "key2": "value2"
    }
  },
  "aiCallId": "call_h435hi34h5i43i5",
  "mode": "manual",
  "conversationStateId": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b"
}

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

Agent-Secret-Key

Agent-Secret-KeystringRequired

Custom authentication header

Body

application/json

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

/external/conversations/start

HTTPcURLJavaScriptPython

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

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

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

Get conversation messages

get

Fetches all messages associated with a specific conversation ID.

Authorizations

Agent-Secret-Key

Agent-Secret-KeystringRequired

Custom authentication header

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

/external/conversations/{id}/messages

HTTPcURLJavaScriptPython

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",
          "userEmail": "text"
        }
      ],
      "fullAIResponse": {
        "reasoning": [
          "text"
        ],
        "outputText": "text",
        "urlCitations": [
          {
            "url": "https://example.com",
            "title": "Example"
          }
        ],
        "fileCitations": [
          {
            "fileId": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
            "filename": "example.txt"
          }
        ]
      }
    }
  ]
}

Send a message to an agent

post

Send a new message to an agent using conversationId.

Authorizations

Agent-Secret-Key

Agent-Secret-KeystringRequired

Custom authentication header

Path parameters

idstringRequired

The ID of the conversation to send a message to.

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

Body

application/json

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

Successfully processed a message to an 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

/external/conversations/{id}/messages

HTTPcURLJavaScriptPython

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",
      "userEmail": "text"
    }
  ],
  "fullAIResponse": {
    "reasoning": [
      "text"
    ],
    "outputText": "text",
    "urlCitations": [
      {
        "url": "https://example.com",
        "title": "Example"
      }
    ],
    "fileCitations": [
      {
        "fileId": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
        "filename": "example.txt"
      }
    ]
  }
}

Send a message to an agent

post

Send a new message to an agent using conversationId.

Authorizations

Agent-Secret-Key

Agent-Secret-KeystringRequired

Custom authentication header

Path parameters

idstringRequired

The ID of the conversation to send a message to.

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

Body

application/json

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

Successfully sent a message to an 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

/external/conversations/{id}/messages/async

HTTPcURLJavaScriptPython

POST /external/conversations/{id}/messages/async 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",
      "userEmail": "text"
    }
  ],
  "fullAIResponse": {
    "reasoning": [
      "text"
    ],
    "outputText": "text",
    "urlCitations": [
      {
        "url": "https://example.com",
        "title": "Example"
      }
    ],
    "fileCitations": [
      {
        "fileId": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
        "filename": "example.txt"
      }
    ]
  }
}

Get response on

get

Fetches response on a specific conversation message ID.

Authorizations

Agent-Secret-Key

Agent-Secret-KeystringRequired

Custom authentication header

Path parameters

idstringRequired

The ID of the conversation to retrieve message for.

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

conversationMessageIdstringRequired

The ID of the conversation message to retrieve response for.

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

Responses

200

Successfully retrieved conversation message.

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

/external/conversations/{id}/messages/{conversationMessageId}/response-on

HTTPcURLJavaScriptPython

GET /external/conversations/{id}/messages/{conversationMessageId}/response-on HTTP/1.1
Host: api.raia2.com
Agent-Secret-Key: YOUR_API_KEY
Accept: */*

{
  "status": "completed",
  "message": {
    "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",
        "userEmail": "text"
      }
    ],
    "fullAIResponse": {
      "reasoning": [
        "text"
      ],
      "outputText": "text",
      "urlCitations": [
        {
          "url": "https://example.com",
          "title": "Example"
        }
      ],
      "fileCitations": [
        {
          "fileId": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
          "filename": "example.txt"
        }
      ]
    }
  },
  "error": "text"
}

Send a manual message to a user

post

Send a manual message to a user in a conversation that is in manual mode. Will fail if the conversation is not in manual mode or is a voice conversation.

Authorizations

Agent-Secret-Key

Agent-Secret-KeystringRequired

Custom authentication header

Path parameters

idstringRequired

The ID of the conversation to send a message to the user.

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

Body

application/json

messagestringRequired

The message that will be sent to the user

Example: Your appointment has been confirmed for tomorrow at 2pm.

conversationMessageIdstringOptional

The ID of the conversation message that the user sent to the AI agent

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

Responses

200

Message sent successfully to the user.

application/json

400

Conversation must be in manual mode and not a voice conversation.

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

post

/external/conversations/{id}/send-manual-message

HTTPcURLJavaScriptPython

POST /external/conversations/{id}/send-manual-message HTTP/1.1
Host: api.raia2.com
Agent-Secret-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 133

{
  "message": "Your appointment has been confirmed for tomorrow at 2pm.",
  "conversationMessageId": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b"
}

{
  "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",
      "userEmail": "text"
    }
  ],
  "fullAIResponse": {
    "reasoning": [
      "text"
    ],
    "outputText": "text",
    "urlCitations": [
      {
        "url": "https://example.com",
        "title": "Example"
      }
    ],
    "fileCitations": [
      {
        "fileId": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
        "filename": "example.txt"
      }
    ]
  }
}