Conversations

The bread and butter of MAAX AI business is generating perfect messages. This section explains in detail how to use the endpoints needed to make that happen.

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

• /inititiate_answer_generation/

• /retrieve_answer

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

• /create-conversation/

• /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:

Answer Generation With MAAX AI

/inititiate_answer_generation

Generates an answer to a message.

POST 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*	String	Contents of the message from your customer.
platform*	String	Where will you be sending the response to? website, email, sms
ai_id	Integer	Leave blank for customer_support_automation service type. For sales_automation service type get the ID from the Sales AI dashboard.
service_type	String	For Customer Support use customer_support_automation. For Sales use sales_automation.
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	{"email":"[email protected]", "phone":"1234567778" "first_name": "student", "last_name":"test"} 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.
conversation_id	Int	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. Please review the /create_conversation/ endpoint if you want to create a conversation and specify an id. Recommended for sales applications.
output_format	String	Leave blank if you wish to receive a plain text response. Use html if you wish to receive a response formatted as html (recommended for sending email responses).

Headers

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

200: OK { "incoming_message_id": Integer }

401: Unauthorized Returned if the provided api key is not valid (or not provided).

400: Bad Request Returned if there are incorrectly formatted parameters

403: Forbidden

/retrieve_answer

Retrieves an answer

GET https://app.maax.ai/api/retrieve_answer/

Path Parameters

Name	Type	Description
service_type*	String	Must be the same as in the /initiate_answer_generation for the given incoming_message_id. Used for security purposes.
incoming_message_id*	Integer	An integer returned by a successfully executed /initiate_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/

200: OK { "answer": String }

400: Bad Request Returned if there are incorrectly formatted parameters

401: Unauthorized Returned if the provided api key is not valid (or not provided).

403: Forbidden Returned if the message you are trying to access does not belong to your company / user.

/create-conversation/

Creates a new conversation instance

POST 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.

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	{ "email": "EMAIL", "phone": "PHONE_NUMBER", "first_name": "FIRST_NAME", "last_name": "LAST_NAME", "instagram": "INSTAGRAM_HANDLE", "facebook": "FACEBOOK_HANDLE" ... } At least one contact information field (phone, email, Instagram, or Facebook) should be given, along with first name and last name.

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/

200: OK { "conversation_id": "CONVERSATION_ID" }

403: Forbidden Returned if trying to access objects that does not belong to the company.

401: Unauthorized Returned if the provided api key is not valid (or not provided).

400: Bad Request Returned if there are incorrectly formatted parameters

/get_conversations_history/

Fetches the history of a given conversation.

GET 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	Used for security purposes. Must match the Conversation object identified by 'conversation_id' above. For Customer Support use customer_support_automation. For Sales use sales_automation.

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/

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.

200: OK { "messages_in_conversation": [MESSAGE1, MESSAGE2, ...] }

400: Bad Request Returned if there are incorrectly formatted parameters

401: Unauthorized Returned if the provided api key is not valid (or not provided).

403: Forbidden Returned if the provided api key is not valid (or not provided).