# Conversations

There are two endpoints required to create and retrieve a message:

* [/inititiate\_answer\_generation](#inititiate_answer_generation)/
* [/retrieve\_answer](#retrieve_answer)

For creating conversations and getting conversation history you can use two other endpoints (used mostly for advanced sales applications):

* [/create-conversation/](#create-conversation)
* [/get\_conversations\_history/](#get_conversations_history)

We highly recommend that you review the visually enhanced explanations of how our API works. As a minimum, please review the following diagram:

<table data-view="cards"><thead><tr><th></th><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th><th data-hidden data-card-cover data-type="files"></th></tr></thead><tbody><tr><td>Answer Generation With MAAX AI</td><td></td><td></td><td><a href="/pages/zf3h14lqoWZPVXjOa5rI">/pages/zf3h14lqoWZPVXjOa5rI</a></td><td></td></tr></tbody></table>

### /inititiate\_answer\_generation

## Generates an answer to a message.

<mark style="color:green;">`POST`</mark> `https://app.max.ai/api/initiate_answer_generation/`

This endpoint tasks MAAX AI with generating a response to a message your company received.

#### Query Parameters

| Name                                               | Type    | Description                                                                                                                                                                                                                                                                                                                                                                                    |
| -------------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| message\_content<mark style="color:red;">\*</mark> | String  | Contents of the message from your customer.                                                                                                                                                                                                                                                                                                                                                    |
| platform<mark style="color:red;">\*</mark>         | String  | <p>Where will you be sending the response to? <br><br><em>website, email, sms</em></p>                                                                                                                                                                                                                                                                                                         |
| ai\_id                                             | Integer | <p>Leave blank for <em>customer\_support\_automation</em> service type. <br><br>For <em>sales\_automation</em> service type get the ID from the <a href="https://app.maax.ai/dashboard/sales-ai/">Sales AI dashboard. </a></p>                                                                                                                                                                 |
| service\_type                                      | String  | <p>For Customer Support use <em>customer\_support\_automation.</em></p><p></p><p>For Sales use <em>sales\_automation.</em> </p>                                                                                                                                                                                                                                                                |
| prospect\_id                                       | Integer | The id of prospect who is asking the question (If it is not provided, the new one will be created based on the prospect\_info)                                                                                                                                                                                                                                                                 |
| prospect\_info                                     | JSON    | <p><code>{"email":"</code><a href="mailto:email@test.com"><code><email@test.com></code></a><code>", "phone":"1234567778" "first\_name": "student", "last\_name":"test"}</code></p><p></p><p>At least one of the contact methods should be provided, along with the first and last names. You can always override these details, so if you do not have a last name, supply a blank string. </p> |
| conversation\_id                                   | Int     | <p>The conversation id between this user and the prospect. If it is not given, the latest conversation between these two will be used, otherwise, a new one will be created.<br><br>Please review the <a href="#create-conversation">/create\_conversation/</a> endpoint if you want to create a conversation and specify an id. Recommended for sales applications.  </p>                     |
| output\_format                                     | String  | <p>Leave blank if you wish to receive a plain text response. <br><br>Use html if you wish to receive a response formatted as html (recommended for sending email responses). </p>                                                                                                                                                                                                              |

#### Headers

| Name                                           | Type   | Description                                                                             |
| ---------------------------------------------- | ------ | --------------------------------------------------------------------------------------- |
| Content-Type<mark style="color:red;">\*</mark> | String | *application/json*                                                                      |
| 2hd-api-key<mark style="color:red;">\*</mark>  | String | Your MAAX AI API key, which you can locate at <https://app.maax.ai/dashboard/api-keys/> |

{% tabs %}
{% tab title="200: OK {     "incoming\_message\_id": Integer }" %}

{% endtab %}

{% tab title="401: Unauthorized Returned if the provided api key is not valid (or not provided). " %}

{% endtab %}

{% tab title="400: Bad Request Returned if  there are incorrectly formatted parameters" %}

{% endtab %}

{% tab title="403: Forbidden " %}

{% endtab %}
{% endtabs %}

### /retrieve\_answer

## Retrieves an answer

<mark style="color:blue;">`GET`</mark> `https://app.maax.ai/api/retrieve_answer/`

#### Path Parameters

| Name                                                    | Type    | Description                                                                                                                                                  |
| ------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| service\_type<mark style="color:red;">\*</mark>         | String  | Must be the same as in the [/initiate\_answer\_generation](#inititiate_answer_generation) for the given *incoming\_message\_id*. Used for security purposes. |
| incoming\_message\_id<mark style="color:red;">\*</mark> | Integer | An integer returned by a successfully executed [/initiate\_answer\_generation](#inititiate_answer_generation)                                                |

#### Headers

| Name        | Type   | Description                                                                                                                    |
| ----------- | ------ | ------------------------------------------------------------------------------------------------------------------------------ |
| 2hd-api-key | String | Your MAAX AI API key, which you can locate at [https://app.maax.ai/shboard/api-keys/](https://app.maax.ai/dashboard/api-keys/) |

{% tabs %}
{% tab title="200: OK {     "answer": String }" %}

{% endtab %}

{% tab title="400: Bad Request Returned if  there are incorrectly formatted parameters" %}

{% endtab %}

{% tab title="401: Unauthorized Returned if the provided api key is not valid (or not provided). " %}

{% endtab %}

{% tab title="403: Forbidden Returned if the message you are trying to access does not belong to your company / user. " %}

{% endtab %}
{% endtabs %}

### /create-conversation/

## Creates a new conversation instance

<mark style="color:green;">`POST`</mark> `https://app.maax.ai/api/create-conversation/`

This function is responsible for creating a conversation for a given prospect. A prospect is identified by their prospect\_id, and additional information about the prospect can be provided in the `prospect_info` field. Most often used in sales conversations, and very rarely for customer support conversations.&#x20;

#### Query Parameters

| Name           | Type    | Description                                                                                                                                                                                                                                                                                                                                  |
| -------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| prospect\_id   | Integer | The id of the prospect for which the conversation is created. If it is not provided, a new prospect will be created based on the `prospect_info`.                                                                                                                                                                                            |
| prospect\_info | JSON    | <p><em>{ "email": "EMAIL", "phone": "PHONE\_NUMBER", "first\_name": "FIRST\_NAME", "last\_name": "LAST\_NAME", "instagram": "INSTAGRAM\_HANDLE", "facebook": "FACEBOOK\_HANDLE" ... }</em><br></p><p>At least one contact information field (phone, email, Instagram, or Facebook) should be given, along with first name and last name.</p> |

#### Headers

| Name                                          | Type   | Description                                                                                                                    |
| --------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------ |
| 2hd-api-key<mark style="color:red;">\*</mark> | String | Your MAAX AI API key, which you can locate at [https://app.maax.ai/shboard/api-keys/](https://app.maax.ai/dashboard/api-keys/) |

{% tabs %}
{% tab title="200: OK {   "conversation\_id": "CONVERSATION\_ID" }" %}

{% endtab %}

{% tab title="403: Forbidden Returned if trying to access objects that does not belong to the company. " %}

{% endtab %}

{% tab title="401: Unauthorized Returned if the provided api key is not valid (or not provided). " %}

{% endtab %}

{% tab title="400: Bad Request Returned if  there are incorrectly formatted parameters" %}

{% endtab %}
{% endtabs %}

### /get\_conversations\_history/

## Fetches the history of a given conversation.

<mark style="color:blue;">`GET`</mark> `https:/app.maax.ai/create-conversation/`

The conversation is identified by its `conversation_id`. If a `service_type` is provided, the function fetches the history specific to that service type.

#### Path Parameters

| Name             | Type    | Description                                                                                                                                                                                                                                                              |
| ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| conversation\_id | Integer | Conversation for which history is desired.                                                                                                                                                                                                                               |
| service\_type    | String  | <p>Used for security purposes. Must match the Conversation object identified by <code>'conversation\_id'</code> above.</p><p></p><p>For Customer Support use <em>customer\_support\_automation.</em></p><p></p><p>For Sales use <em>sales\_automation.</em> <br><br></p> |

#### Headers

| Name        | Type   | Description                                                                             |
| ----------- | ------ | --------------------------------------------------------------------------------------- |
| 2hd-api-key | String | Your MAAX AI API key, which you can locate at <https://app.maax.ai/dashboard/api-keys/> |

{% tabs %}
{% tab title="405: Method Not Allowed If the request method is not GET, it responds with an error message "Invalid request method" and an HTTP 405 status code." %}

{% endtab %}

{% tab title="200: OK {   "messages\_in\_conversation": \[MESSAGE1, MESSAGE2, ...] }" %}

{% endtab %}

{% tab title="400: Bad Request Returned if  there are incorrectly formatted parameters" %}

{% endtab %}

{% tab title="401: Unauthorized Returned if the provided api key is not valid (or not provided). " %}

{% endtab %}

{% tab title="403: Forbidden Returned if the provided api key is not valid (or not provided). " %}

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://documentation.maax.ai/main/technical-guides/apis/v1/conversations.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.