# 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="../../explanatory-diagrams/answer-generation-with-maax-ai">answer-generation-with-maax-ai</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 %}