💻API

An alternative to our SDK - for submitting custom attributes to new or existing customers.

What can you use the Mava API for?

1. Custom Attributes: You can use the Mava API to push user attributes to Mava via the identify endpoint. This offers similar functionality to the web chat SDK but can be used with all integration options and enables you to push data from third-party systems, such as your database, into Mava.

2. Status Updates: You can use the API to update ticket statuses, for example to close them.

3. Ticket Updates: You can use the API to update tickets, for example adding a tag or category.

4. Private Notes: You can use the API to add private notes to tickets.

5. Messages: sending messages via API is coming soon.

6. Creating Tickets: creating tickets is coming soon

We're expanding our API so if you're looking to build more with the Mava API please send us a message or book a feedback call.

Getting Started

Head over to the API section within the Mava dashboard and create an API key.

Please note: If you send no customer ID, a customer will be created for you and a new customer ID sent back which should be stored and used for subsequent calls to update that same customer.

CURL

curl -X POST https://gateway.mava.app/api/identify \
  -H "Content-Type: application/json" \
  -d '{
    "emailAddress": "",
    "mavaCustomerId": "",
    "customAttributes": [
      {
        "label": "exampleLabel",
        "value": "exampleValue"
      }
    ]
  }'

NodeJS

fetch('https://gateway.mava.app/api/identify', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-auth-token': 'YOUR_AUTH_TOKEN_HERE'
  },
  body: JSON.stringify({
    emailAddress: '', 
    mavaCustomerId: '',
    customAttributes: [
      {
        label: 'exampleLabel',
        value: 'exampleValue'
      }
    ]
  })
})
.then(response => response.json())
.then(data => console.log(data))
.catch((error) => console.error('Error:', error));

Schema

{
  "type": "object",
  "properties": {
    "emailAddress": {
      "type": "string"
    },
    "plaformUserId": {
      "type": "string"
    },
    "mavaCustomerId": {
      "type": "string"
    },
    "customAttributes": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "label": {
            "type": "string"
          },
          "value": {
            "type": "string"
          }
        },
        "required": ["label", "value"]
      }
    }
  }
}

API Endpoints

1. Get Categories

Retrieves a list of all active categories for the authenticated client.

Endpoint

GET /api/categories

Authentication

• Requires API token authentication

• Subject to rate limiting

Response

Success (200 OK)

{
  "categories": [
    {
      "_id": "string",
      "name": "string"
    }
  ]
}

Error (500 Internal Server Error)

{
  "error": "Internal server error"
}

2. Update Ticket

Updates a ticket's status, priority, and/or category.

Endpoint

PUT /api/ticket

Authentication

• Requires API token authentication

• Subject to rate limiting

Request Body

Field	Type	Required	Description
ticketId	string	Yes	The unique identifier of the ticket
status	string	No	New ticket status
priority	number	No	New priority level
categoryId	string	No	ID of the category to assign

Valid Values

• Status: "Open", "Resolved", "Pending", "Waiting"

• Priority: 1, 2, 3

• CategoryId: Must be a valid category ID from GET /categories

Response

Success (200 OK)

{
  "message": "Ticket updated"
}

Error Responses

Ticket not found (400)

{
  "error": "Ticket not found"
}

Invalid category (400)

{
  "error": "Category not found"
}

Invalid status/priority (400)

{
  "error": "Invalid status or priority"
}

Server error (500)

{
  "error": "Internal server error"
}

Behavior

• Each change (status, priority, category) creates an audit log message

• Changes are only made if the new value differs from the current value

• Category must be active (not archived) and belong to the client