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:

searchKeywordstringOptional

Search keyword in conversation title, summary, agent name, user first and last name, email and phone number

userIdstring · uuidOptional

Conversation user ID

startDatestring · date-timeOptional

Start date of conversation updatedAt.

Example: 2024-03-20T12:00:00Z

endDatestring · date-timeOptional

End date of conversation updatedAt.

Example: 2024-03-20T12:00:00Z

withFeedbacksOnlybooleanOptional

If true, returns conversations with at least one feedback

Responses

200

Successfully received conversations.

application/json

currentPagenumberRequired

Current page

pageSizenumberRequired

Page size

totalItemsnumberRequired

Total items

totalPagesnumberRequired

Total pages

hasNextPagebooleanRequired

Has next page

hasPreviousPagebooleanRequired

Has previous page

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",
      "user": {
        "id": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
        "firstName": "John",
        "lastName": "Doe",
        "context": "Support",
        "source": "webchat",
        "fkId": "123456",
        "fkUserId": "123456",
        "email": "[email protected]",
        "phoneNumber": "[phone]",
        "metadata": {
          "customData": {
            "key1": "value1",
            "key2": "value2"
          }
        }
      },
      "createdAt": "2023-10-01T12:00:00Z",
      "updatedAt": "2023-10-01T12:00:00Z",
      "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",
  "user": {
    "id": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
    "firstName": "John",
    "lastName": "Doe",
    "context": "Support",
    "source": "webchat",
    "fkId": "123456",
    "fkUserId": "123456",
    "email": "[email protected]",
    "phoneNumber": "[phone]",
    "metadata": {
      "customData": {
        "key1": "value1",
        "key2": "value2"
      }
    }
  },
  "createdAt": "2023-10-01T12:00:00Z",
  "updatedAt": "2023-10-01T12:00:00Z"
}

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

idstring · uuidRequired

Conversation state ID

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

namestringRequired

Conversation state name

descriptionstring · nullableRequired

Conversation state description

colorstring · nullableRequired

Conversation state color hex

isPersistentbooleanRequired

True if conversation state is persistent

createdAtstringRequired

Conversation state created at

Example: 2023-01-01T00:00:00.000Z

updatedAtstringRequired

Conversation state created at

Example: 2023-01-01T00:00:00.000Z

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

idstringRequired

New conversation ID

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

conversationUserIdstringRequired

Conversation user ID

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

titlestringOptional

Conversation title

Example: Conversation Title

scorenumberOptional

Conversation score

Example: 4

summarystringOptional

Conversation summary

Example: This is a summary of the conversation.

aiConversationIdstringRequired

AI conversation ID

Example: conv_h435hi34h5i43i5sdfdfs

metadataobjectOptional

Conversation metadata

Example: {"customData":{"key1":"value1","key2":"value2"}}

aiCallIdstringOptional

AI call ID

Example: call_h435hi34h5i43i5

modestring · enumOptional

Conversation mode

Example: manualPossible values:

conversationStateIdstringOptional

Conversation state ID

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

createdAtstring · date-timeRequired

Date the conversation was created

Example: 2023-10-01T12:00:00Z

updatedAtstring · date-timeRequired

Date the conversation was updated

Example: 2023-10-01T12:00:00Z

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",
  "user": {
    "id": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
    "firstName": "John",
    "lastName": "Doe",
    "context": "Support",
    "source": "webchat",
    "fkId": "123456",
    "fkUserId": "123456",
    "email": "[email protected]",
    "phoneNumber": "[phone]",
    "metadata": {
      "customData": {
        "key1": "value1",
        "key2": "value2"
      }
    }
  },
  "createdAt": "2023-10-01T12:00:00Z",
  "updatedAt": "2023-10-01T12:00:00Z",
  "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:

conversationStateIdstringOptional

Conversation state ID

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

Responses

200

Successfully updated the conversation.

application/json

idstringRequired

New conversation ID

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

conversationUserIdstringRequired

Conversation user ID

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

titlestringOptional

Conversation title

Example: Conversation Title

scorenumberOptional

Conversation score

Example: 4

summarystringOptional

Conversation summary

Example: This is a summary of the conversation.

aiConversationIdstringRequired

AI conversation ID

Example: conv_h435hi34h5i43i5sdfdfs

metadataobjectOptional

Conversation metadata

Example: {"customData":{"key1":"value1","key2":"value2"}}

aiCallIdstringOptional

AI call ID

Example: call_h435hi34h5i43i5

modestring · enumOptional

Conversation mode

Example: manualPossible values:

conversationStateIdstringOptional

Conversation state ID

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

createdAtstring · date-timeRequired

Date the conversation was created

Example: 2023-10-01T12:00:00Z

updatedAtstring · date-timeRequired

Date the conversation was updated

Example: 2023-10-01T12:00:00Z

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: 158

{
  "title": "Updated Conversation Title",
  "context": "Updated conversation context",
  "status": "active",
  "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",
  "user": {
    "id": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
    "firstName": "John",
    "lastName": "Doe",
    "context": "Support",
    "source": "webchat",
    "fkId": "123456",
    "fkUserId": "123456",
    "email": "[email protected]",
    "phoneNumber": "[phone]",
    "metadata": {
      "customData": {
        "key1": "value1",
        "key2": "value2"
      }
    }
  },
  "createdAt": "2023-10-01T12:00:00Z",
  "updatedAt": "2023-10-01T12:00:00Z"
}

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: 503

{
  "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",
  "authorId": "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

questionMessageIdstringRequired

The ID of the question message to retrieve response for. (The message that the user sent to the AI agent)

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

Responses

200

Successfully retrieved conversation message.

application/json

statusstring · enumRequired

Response status

Example: completedPossible values:

errorstring · nullableRequired

Response error

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/{questionMessageId}/response-on

HTTPcURLJavaScriptPython

GET /external/conversations/{id}/messages/{questionMessageId}/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"
}

Update conversation mode

put

Updates conversation mode. 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

modestring · enumOptional

Conversation mode

Example: aiPossible values:

Responses

200

Successfully updated the conversation mode.

application/json

idstringRequired

New conversation ID

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

conversationUserIdstringRequired

Conversation user ID

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

titlestringOptional

Conversation title

Example: Conversation Title

scorenumberOptional

Conversation score

Example: 4

summarystringOptional

Conversation summary

Example: This is a summary of the conversation.

aiConversationIdstringRequired

AI conversation ID

Example: conv_h435hi34h5i43i5sdfdfs

metadataobjectOptional

Conversation metadata

Example: {"customData":{"key1":"value1","key2":"value2"}}

aiCallIdstringOptional

AI call ID

Example: call_h435hi34h5i43i5

modestring · enumOptional

Conversation mode

Example: manualPossible values:

conversationStateIdstringOptional

Conversation state ID

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

createdAtstring · date-timeRequired

Date the conversation was created

Example: 2023-10-01T12:00:00Z

updatedAtstring · date-timeRequired

Date the conversation was updated

Example: 2023-10-01T12:00:00Z

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}/mode

HTTPcURLJavaScriptPython

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

{
  "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.",
  "aiConversationId": "conv_h435hi34h5i43i5sdfdfs",
  "metadata": {
    "customData": {
      "key1": "value1",
      "key2": "value2"
    }
  },
  "aiCallId": "call_h435hi34h5i43i5",
  "mode": "manual",
  "conversationStateId": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
  "user": {
    "id": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
    "firstName": "John",
    "lastName": "Doe",
    "context": "Support",
    "source": "webchat",
    "fkId": "123456",
    "fkUserId": "123456",
    "email": "[email protected]",
    "phoneNumber": "[phone]",
    "metadata": {
      "customData": {
        "key1": "value1",
        "key2": "value2"
      }
    }
  },
  "createdAt": "2023-10-01T12:00:00Z",
  "updatedAt": "2023-10-01T12:00:00Z"
}

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

authorIdstringOptional

Author platform ID

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

Responses

200

Message sent successfully to the user.

application/json

idstringRequired

Conversation message ID

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

messagestringRequired

Conversation message content

Example: Hello, how can I help you?

rawMessagestringOptional

Raw message content

Example: Raw message example

conversationIdstringRequired

Conversation ID

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

senderRolestring · enumRequired

Sender role in the conversation

Example: conversation_userPossible values:

conversationMessageIdstringRequired

Question message ID

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

sourcestring · enumRequired

Conversation source

Example: apiPossible values:

createdAtstring · date-timeRequired

Message create date

Example: 2022-01-01T00:00:00.000Z

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: 183

{
  "message": "Your appointment has been confirmed for tomorrow at 2pm.",
  "conversationMessageId": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
  "authorId": "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"
      }
    ]
  }
}