Documents

How to Use Maya

How to Use Maya (Alchemyst AI Persona)

Overview

Maya is a persona within the Alchemyst AI platform designed to assist with sales development, campaign management, chat automation, lead augmentation, integrations, and email workflows. This guide provides comprehensive instructions, API references, and usage examples on how to interact with Maya using the Alchemyst AI API.

Getting Started

Authentication

Many Maya endpoints require authentication using JWT Bearer tokens. Authenticate via OAuth providers (Google, Atlassian, Zoho) or API key, as described in the /api/auth/google, /api/auth/atlassian, and /api/auth/zoho endpoints. Include the token in the Authorization header:

``` Authorization: Bearer <your_token> ```

Chat with Maya

Generate a Chat Response

Maya responds to chat prompts via the /api/v1/chat endpoint.

Endpoint

  • POST /api/v1/chat
  • Body:
    • chat_history: Array of user/assistant messages. Required.
    • persona: Set to "maya" to use the Maya persona.

Example Request

```json { "chat_history": [ { "role": "user", "content": "Hello Maya, can you help me draft a sales email?" } ], "persona": "maya" } ```

Example Response

```json { "result": { "message": "Sure! Here is a draft sales email...", "persona": "maya" }, "metadata": { "timeTaken": 150 } } ```

Additional Options

  • Use /api/v1/chat/generate/stream for streaming chat responses with real-time thinking steps.
  • Use /api/v1/chat/new to save new chat histories.
  • Fetch previous chats with /api/v1/chat/history and /api/v1/chat/fetch/{chatId}.

Campaign Management Using Maya

List Campaigns

Retrieve all campaigns filtered by persona (default: maya):

  • GET /api/v1/campaigns/list?persona=maya

Generate Campaign Content

Generate or rephrase emails/social content for a campaign:

  • POST /api/v1/campaigns/generate/{campaignId}
  • Body includes action, campaignId, template, type (e.g., email), leads info, current content, campaign history, and (optionally) context.

Example Request

```json { "action": "create", "campaignId": "campaign123", "template": "Intro Email", "type": "email", "leads": [ { "name": "John Doe", "email": "john@example.com" } ], "currentContent": {}, "campaignHistory": [] } ```

Generate Email Content as Maya

Use persona-specific email generation:

  • POST /api/v1/maya/generate/content/emails
  • Body:
    • chat_history: Array of chat messages in Langchain format.
    • scope: [Optional] Defaults to "internal".

Example Request

```json { "chat_history": [ { "role": "user", "content": "Write an engaging email introduction." } ], "scope": "internal" } ```

Integrations with Maya

Overview

Maya supports integrations with platforms such as Telegram, WhatsApp, Twilio, and Zoho for multi-channel automation and communication. These endpoints are organized under /api/v1/maya/integrations/{integrationName} and related routes.

Listing and Managing Integrations

  • GET /api/v1/maya/integrations – List configured integrations for Maya persona.
  • GET /api/v1/maya/integrations/marketplace – List available integrations to configure for Maya.

Initialize Telegram Integration

  • POST /api/v1/maya/integrations/telegram/init
  • Body: Requires phoneNumber, profileHandle, apiKey.

Initialize WhatsApp Integration

  • POST /api/v1/maya/integrations/whatsapp/init
  • Body: Requires WhatsApp business credentials and API key.

Example (Initialize Zoho Integration)

```json { "code": "zohoOauthCode", "clientId": "yourZohoClientId", "clientSecret": "yourZohoSecret", "userId": "user123", "apiKey": "alchemystApiKey", "organizationId": "org456", "persona": "maya" } ```

Persona Instructions for Maya

You can retrieve or set custom instructions for how Maya behaves in chats:

  • GET /api/v1/instructions?persona=maya – Get current instructions
  • POST /api/v1/instructions – Set or update instructions (requires authentication and admin rights)

Lead Augmentation and Contextual Enhancement

Augment Leads via Web

  • POST /api/v1/leads/augment/web
  • Body: userPrompt, dataForSearchQuery
  • Scope: Use persona-level instruction to have Maya handle the request.

Add or Search Context for Maya

  • POST /api/v1/context/add – Add resources or instructions as context
  • POST /api/v1/context/search – Query previously provided context

Example Workflows

Example: Sending an Email Campaign as Maya

  1. Authenticate and obtain Bearer token.
  2. Generate campaign content via /api/v1/campaigns/generate/{campaignId} with persona set to "maya".
  3. Schedule or send emails in batch using /api/v1/batch/emails/schedule or /api/v1/emails/send/batch.

Additional Maya Endpoints

  • /api/v1/{persona}/generate/workbench/components – Generate custom workbench components for Maya
  • /api/v1/{persona}/integrations/{integrationName}/list – List specific integrations by type

Error Handling

  • Unauthorized requests (missing or invalid tokens) return 401 errors.
  • Forbidden requests (insufficient permissions) return 403 errors.
  • Not Found or server errors will return 404 or 500 with descriptive messages.

Security

  • Use BearerAuth/JWT for all endpoints marked as security: bearerAuth.
  • Protect credentials and never share your API key or tokens publicly.

Notes

  • All endpoint fields, required parameters, and request/response structure must be strictly followed.
  • See each endpoint above for specific request/response formats and field details.
  • For unknown or missing persona features, refer to the API’s error response for "Context not found".

References