NAV navbar
Back to Marketbase
javascript bash

Introduction

Marketbase is a platform to proactively monitor conversations within marketplaces. If your team is using a popular third party service for messaging, we encourage you to use our no-code integrations. If you are using a custom platform or one that is not supported yet, we provide the following API to send data to Marketbase.

Get started

Live API Url: https://live.marketbaseapi.com
Sandbox API Url: https://sandbox.marketbaseapi.com

To get started, sign up for Marketbase to create your account.

Once logged in:

  1. Create a new workspace
  2. Open your new workspace
  3. Go to 'Settings' page
  4. Within the 'API keys' section, click on '+ Add key' and follow the directions to finish adding the key.
  5. Back on the 'Settings' page, you should now see your API USERNAME and PASSWORD that you will use in the following steps for Authentication.

We provide an NPM package for use in server-side NodeJS applications.

npm install --save @marketbase/api

Authentication

import Marketbase from "@marketbase/api";

const client = createClient(
  process.env.MARKETBASE_USERNAME,
  process.env.MARKETBASE_PASSWORD
);

Make sure to set the environment variables to the correct username and password.

Marketbase uses a username and password pair to allow access to the API through Basic HTTP Authentication.

You can manage your credentials on the API keys section of the dashboard. Keep your credentials secure as they can be used to view your information.

Example 1: Creating a conversation between a merchant and a buyer

1. Create Users for the merchant and buyer.

// Create the merchant user
await client.users.create({
  "metaId": "usx_4381667227078356",
  "displayName": "Trailer Swift"
});

// Create the customer user
await client.users.create({
  "metaId": "usx_7681667227078356",
  "displayName": "Nancy Mover"
});

The metaId and displayName values are required when creating a user. The metaId should match the ID of that user in your system as you can use that to reference the user in Marketbase. The displayName will be displayed in the UI, we recommend using their first name and last name.

Optionally, you can also pass an emailAddress that will be used for notifications whenever a message is received.

2. Create Channel for your conversation

// Create the Channel
await client.users.create({
  "metaId": "order_8161667227078356",
  "subject": "10ft Moving Truck Rental - AWD",
  "participantUserMetaIds": [
    "usx_4381667227078356",
    "usx_7681667227078356"
  ]
});

Create the Channel that will host the conversation. Use the order id in your system in the metaId and pass subject that will be displayed in the UI. Use the metaIds in the participantMetaUserIds array to register which users are involved in that Channel.

The publicDetails array is optional, but it will be displayed in the sidebar.

3. Create a HistoryEvent with the reservation message

await client.channels.createHistoryEvent({
  "channelMetaId": "order_8161667227078356",
  "body": "Reservation created"
});

You can optionally create a HistoryEvent to record the beginning of the channel and conversation.

4. Create a MessageEvent with the reservation message

await client.channels.createMessageEvent({
  "channelMetaId": "order_8161667227078356",
  "userMetaId": "usx_4381667227078356",
  "body": "Thank you for your purchase"
});

Create a MessageEvent whenever a user sends a message.

Channel

Channels represent an interaction between multiple Users on your platform and it's the main container for events.

Channel attributes

{
  "data": {
    "id": "channel_EXVPCzU5wqsSiwbw",
    "type": "Channel",
    "createdAt": "2022-10-31T14:37:59.622Z",
    "updatedAt": "2022-10-31T14:37:59.622Z",
    "meta": {},
    "metaId": "order_8161667227078356",
    "participantUserIds": [
      "user_dHNaz3HTPz5BXt8j",
      "user_X1racVmmbQMU7Mma"
    ],
    "publicDetails": [],
    "subject": "10ft Moving Truck Rental - AWD"
  }
}
Attribute Description
id string read only Marketbase ID for the Channel. This is generated when the Channel if first created
type string read only "Channel"
createdAt ISO8601 string Creation date of the channel. It defaults to the current time if it's not provided during creation.
updatedAt ISO8601 string read only Update date
metaId string Corresponding id of this Channel in your platform. This can be used to reference the channel when creating events
meta Object Additional data to help annotate the model
subject string Used to identify the channel in the dashboard.
publicDetails detail objects array Array of objects with a label and value properties. This is displayed in the dashboard sidebar and can be used to provide more context about the channel.
participantUserIds strings array IDs of the users that are participating in this conversation

Creating a Channel

await marketbaseClient.channels.create({
  metaId: "order_xxxxxxxxxxxxxxxx",
  participantUserMetaIds: ["myUser123", "myOtherUser123"],
  subject: "Kayak tour in Fajardo, Puerto Rico",
});
POST /v1/channels
{
  "metaId": "order_xxxxxxxxxxxxxxxx",
  "participantUserMetaIds": ["myUser123", "myOtherUser123"],
  "subject": "Kayak tour in Fajardo, Puerto Rico"
}

This endpoint verifies that a channel with the metaId doesn't already exist before creating it. It returns a 409 Conflict error if that channel already exists.

Attribute type
metaId string required
createdAt ISO8601 string optional
subject string optional
participantUserMetaIds strings array optional
publicDetails detail objects array optional

Upserting a Channel

PUT /v1/channels
{
  "metaId": "order_xxxxxxxxxxxxxxxx",
  "participantUserMetaIds": ["myUser123", "myOtherUser123"],
  "subject": "Kayak tour in Fajardo, Puerto Rico"
}

This endpoint finds and updates a channel based on the metaId, creating it if it doesn't already exist.

Attribute type
metaId string required
createdAt ISO8601 string optional
subject string optional
participantUserMetaIds strings array optional
publicDetails detail objects array optional

Getting a channel

await marketbaseClient.channels.fetch("channel_1209308744343443");
GET /v1/channels/channel_1209308744343443

Listing channels

await marketbaseClient.channels.list({});
GET /v1/channels

Users

Users are entities that can interact in a channel. ExternalUsers are a type of users used to represent the users in your platform.

ExternalUser attributes

{
  "data": {
    "id": "user_dHNaz3HTPz5BXt8j",
    "type": "ExternalUser",
    "createdAt": "2022-10-31T14:37:58.804Z",
    "updatedAt": "2022-10-31T14:37:58.804Z",
    "displayName": "Trailer Swift",
    "emailAddress": null,
    "metaId": "usx_4381667227078356",
    "meta": {}
  }
}
Parameter Description
id string
type string "ExternalUser"
createdAt ISO8601 string Creation date
updatedAt ISO8601 string Update date
metaId string Corresponding id of this Channel in your platform. This can be used to reference the channel when creating events
meta Object Additional data to help annotate the model
displayName string Name of this user to be used for display in the inbox and emails. Defaults to the id
emailAddress string Email address.

Creating an ExternalUser

await marketbaseClient.users.create({
  "metaId": "usx_4381667227078356",
  "displayName": "Trailer Swift"
});
POST /v1/users
{
  "metaId": "usx_4381667227078356",
  "displayName": "Trailer Swift"
}

This endpoint verifies that a user with the metaId doesn't already exist before creating it. It returns a 409 Conflict error if that user already exists.

Attribute type
metaId string required
displayName string
emailAddress string
createdAt ISO 8601 string

Upserting an ExternalUser

PUT /v1/users
{
  "metaId": "usx_4381667227078356",
  "displayName": "Trailer Swift"
}

This endpoint finds and updates a user based on the metaId, creating it if it doesn't already exist.

Attribute type
metaId string - required
displayName string
emailAddress string
createdAt ISO 8601 string

Getting a user

await marketbaseClient.users.fetch("user_1209308744343443");
GET /v1/users/user_1209308744343443

Listing users

await marketbaseClient.users.list({});
POST /v1/users

Events

Events are individual actions added to a timeline. They come from many different sources and can handle different interactions.

HistoryEvent attributes

await marketbaseClient.events.createHistory({
  "channelMetaId": "order_8161667227078356",
  "body": "Reservation created"
});
POST /v1/events
{
  "type": "HistoryEvent",
  "channelMetaId": "channel_1092373732323",
  "body": "Reservation created",
}
{
  "data": {
    "id": "ev_e4NvtCbM75MHBu8W",
    "type": "HistoryEvent",
    "createdAt": "2022-10-31T14:37:59.985Z",
    "updatedAt": "2022-10-31T14:37:59.985Z",
    "body": "Reservation created",
    "channelId": "channel_EXVPCzU5wqsSiwbw"
  }
}

HistoryEvents are simple events

Parameter Description
id (string - read only)
type (string - read only) "HistoryEvent"
createdAt (ISO 8601 string) Creation date
updatedAt (ISO 8601 string - read only) Update date
channelId (string - read only) Parent channel id
body (string) Display text

MessageEvent attributes

await marketbaseClient.events.createMessage({
  "channelMetaId": "order_8161667227078356",
  "userMetaId": "usx_4381667227078356",
  "body": "Thank you for your purchase"
});
POST /v1/events
{
  "type": "MessageEvent",
  "channelMetaId": "channel_1092373732323",
  "userMetaId": "user_03980947903fy4"
  "body": "Thank you for your reservation",
}
{
  "data": {
    "id": "ev_gwZxub5KcH2vu5X8",
    "type": "MessageEvent",
    "createdAt": "2022-10-31T14:38:00.444Z",
    "updatedAt": "2022-10-31T14:38:00.444Z",
    "body": "Thank you for your purchase",
    "channelId": "channel_EXVPCzU5wqsSiwbw",
    "userId": "user_dHNaz3HTPz5BXt8j"
  }
}

MessageEvent are messages in a conversation

Parameter Description
id (string - read only)
type (string - read only) "HistoryEvent"
createdAt (ISO 8601 string) Creation date
updatedAt (ISO 8601 string - read only) Update date
channelId (string - read only) Parent channel id
body (string) Display text
metaUserId (string) Reference id
javascript bash