API Documentation

Introduction

This site shows the full documentation for our HTTP API. It is split into sections according to API resources, each of them listing all of their endpoints.
The documentation is designed to be an interactive web application: You may execute all HTTP calls it describes, simply by filling in the parameters (if any) and hitting Submit.

Current System Status

You may view the current status of our API and all related sub-systems on our Status Page.

Data types

We exclusively use JSON as the data type for all our endpoints, except those that allow uploading arbitrary media files: These endpoints expect the MIME type of the media file to be sent in the Content-Type header.
You can find a detailed list of all field types used on the Types page.

SDKs and packages for your programming language

We provide a range of API clients for different programming languages on GitHub and the languages package repositories, if available.
Please take a look at our repositories to get started quickly.

Authentication and Authorization

We use OAuth 2.0 for authorization and act as an identity provider. You can read more in the authentication page.

This page describes all available data types used throughout the API.

Entity types
Channel
Properties
NAME TYPES DESCRIPTION
uuidlock
string

Channel UUID

identifierlock
string

Channel identifier

messengerlock
string

Name of the messenger used by this channel

caption
string

Channel caption

recipient
string

Recipient name

webhook
string|null

Webhook UUID

active
boolean|null

Whether the channel is active

billing
string|null

Billing method – “ppa” or “mau”

Authenticating to the API

The MessengerPeople API uses the OAuth 2.0 standard for authorization exclusively. Please don’t worry if you’re not too involved with OAuth, this page will walk you through implementing all things auth.
If you’ve done this a few times, however, please just skip to the endpoint summary at the bottom of this page where you’ll find all the details you need.

For most use cases involving a backend application “talking” to an API, there is no human involved. If you intend to create an integration for your server-side applications, you can skip to the Client credentials grant straight away.
Otherwise, you’ll want to look at the Authorization code grant.

Supported grant types

The MessengerPeople Auth server supports the following grant types:

Client credentials grant

The client credentials grant is appropriate for machine-to-machine interaction with no user being involved. The gist of it is you application exchanging a credential pair against an access token. The token will eventually expire, in which case you’ll need to request a new access token from the Auth server.
This is assuming you’ve got your client configured and both client_id and client_secret at hand. If you don’t take a look at the client registration section first. To obtain an access token, make a POST request like so:

POST /token HTTP/1.1
Host: auth.messengerpeople.dev
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&
client_id=<YOUR_CLIENT_ID>&
client_secret=<YOUR_CLIENT_SECRET>&
scope=<YOUR_SPACE_SEPARATED_LIST_OF_SCOPES>

If the client exists and the secret is valid, the server will send the following response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "access_token": "a50a01069bd00e0e269ff639d9ca7def",
    "token_type": "bearer",
    "expires_in": 3600,
}

The access_token field contains the access token (quite the surprise, I know) used to authenticate to the actual API, the expires_in field contains the number of seconds until the token becomes invalid as an integer. Do not rely on this value being exactly an hour like in the example above: We may tweak the expiration at any time depending on security observations: It might very well be that this comes down to 10 minutes at some point.
This means that your application will need to keep track of the expiration and perform the above POST call again to obtain a new token in time.
The token_type field is always set to the string “Bearer” as defined by the OAuth specification, but irrelevant for our implementation.

After you’ve got your token, you can perform actual API requests by including it in the Authorization header of your requests, with the authorization type set to Bearer:

GET / HTTP/1.1
Host api.messengerpeople.dev
Authorization: Bearer a50a01069bd00e0e269ff639d9ca7def

More resources:

Authorization code grant

This section is not ready yet. We’ll update it soon.

Refresh token grant

This section is not ready yet. We’ll update it soon.

Client registration

To authorize to the API, you need to create a new client application first. Clients represent a single application accessing the API: Think of the Facebook app, for example, which is a client to the Facebook API servers.
The same applies for backend services – a server might authorize to the central logging system as a client, too.

You can create these clients easily from the app dashboard at app.messengerpeople.dev/settings/oauth-apps. Click on the bottom-right plus button to show the dialog.
You’ll need to provide the following fields:

  • Application name:
    The display name of your application. This will be shown both in your dashboard and to users on the authorization screen, should you use interactive user authorization.
  • Description:
    A short description of your application: What does it do? Again, this will be shown on the authorization screen and may serve as a reminder of what this client has been created for, despite being optional.
  • Redirect URI:
    The URL users will be redirected to after granting permissions to your client. Since this only happens in the interactive authorization flows, you won’t need it for machine-to-machine authorization using the Client Credentials Grant.
    Keep in mind that you may only register a single redirect URI for a client and that this URL must match exactly.
  • Scopes:
    All scopes your application requires. Scopes are permissions, basically: The API has fine-grained scopes to allow access to and modification of different sets of data. By only checking those scopes your application requires, you can be both sure the resulting tokens cannot be abused and making mistakes won’t cause too much damage.
    See the scopes section for more information.

After saving the new client, a unique ID and secret will be generated: These are the values you need in your application code. Please be aware that these credentials can be used to obtain access tokens from the Auth server.

In case your client secret gets compromised, you may generate a new secret in the dashboard at any time. This will take effect immediately, so keep in mind that your application will stop working if you do this 😃

Endpoints

There are two primary endpoints you will be using during the OAuth process. The authorization endpoint is where the users will be directed to begin the authorization flow. After the application obtains an authorization code, it will exchange that code for an access token at the token endpoint. The token endpoint is also responsible for issuing access tokens for other grant types.

Authorization endpoint

The authorization endpoint is available at https://auth.messengerpeople.dev/authorize. You do not need this endpoint for the client credentials grant.

Token endpoint

The token endpoint is available at https://auth.messengerpeople.dev/token. This endpoint only accepts POST requests with url-encoded request bodies.

Scopes

The OAuth server supports a wide range of scopes, all of which you can find below:

  • messages:send
    Send outgoing messages to users
  • messages:read
    Read messages
  • media:create
    Create media objects
  • messenger:settings
    Manage Messenger Settings (e.g. profile image)
  • crm:admin
    Admin access to the Slingshot CRM
  • user:profile
    Access the user profile
  • user:scopes
    Access the users scopes
  • invoices:read
    Access and download all invoices
  • crm:billing
    Access billing
  • messages:delete
    Delete messages

Scopes apply to clients and users as well as access tokens in a most restricted fashion. This means that a token always has the smallest common set of scopes for user and client.
Considering, for example, user John has the scopes AB and C. He uses the application ACME, which has the scopes A and C, but not B. The resulting access token won’t include scope B. It works the same the other way around: If John uses the EMCA application with scopes C and D, the token will only include the shared scope C.

When creating a client, you can choose freely from all scopes. As a best practice, however, you should try to only choose the scopes actually required by your application. This helps to keep attack surface small for compromised clients and prevents damage due to misconfiguration or accidental API calls.

Endpoint summary

The authorization server is available at https://auth.messengerpeople.dev. It supports all standard OAuth 2.0 endpoints as outlined below, including the special /api/me endpoint to retrieve own user profile information.

Method Endpoint Description
POST /token The token endpoint. All grants may retrieve their token here.
GET /authorize The authorization page. Only used for grant types involving user interaction.
POST /authorize The authorization endpoint. Used to obtain authorization codes.

WhatsApp Business API

Many of you are interested in WhatsApp Business and we totally get the point. WhatsApps approach to an API is a little bit more complicated than you’re used to.

First of all: WhatsApp doesn’t host the API themselves. This is a necessary step to ensure end-to-end encryption and making sure that no unencrypted messages flow through the WhatsApp servers.

To use the WhatsApp Business API you need a so called “Business Solution Provider” (BSP). Good news: We are one.

To get access to the WhatsApp Business API your company / use case must be approved by WhatsApp first. There are a few steps and details that you must complete before getting your access.

1: Create a Facebook Business Manager ID

If you don’t have a Facebook Business Manager, you can create one here:

https://business.facebook.com

2: Verify your business

Everything you need to know is summarized in this article, created by Facebook

https://www.facebook.com/business/help/2058515294227817?id=180505742745347

3: Get the WhatsApp Approval. (1 – 2 business days)

Log in to https://app.messengerpeople.dev and navigate to Channels -> WhatsApp Business. Create a new account and provide all the information we ask you for.

After we received your request, we will create a WABA (WhatsApp Business Account) with the Facebook Business Manager ID provided.

IMPORTANT! The Facebook Business Manager ID MUST belong to the business that is asking for approval.

If you’re an agency / developer and build an integration on behalf of your customer, we need the FBM ID of your customer, since they must be approved.

Be aware that your use case must comply with the

Business Policies: https://www.whatsapp.com/legal/business-policy/

Commerce Policies: https://www.whatsapp.com/legal/commerce-policy/

Opt-In Requirements: https://developers.facebook.com/docs/whatsapp/guides/opt-in

4: Give us permissions (< 5 minutes)

After you submitted your request we create the WABA. You will then receive a notification in your Facebook Business Manager, asking you for permission to send WhatsApp messages on your behalf.

https://business.facebook.com/settings/requests

Accept this request. As soon as you accepted the request and your Business Verification is done, WhatsApp will start the approval process.

Facebook also wrote an article about this topic. You can find it here https://www.facebook.com/business/help/524220081677109?id=2129163877102343

5: Waiting for approval

WhatsApp is now checking your application. When you comply with the business policies and commerce policies, you will be approved. After the approval, we will send you an email.

6: Activating a phone number (< 5 minutes)

As soon as steps 1 – 5 are complete, we can create the actual account and register a phone number. We can use a phone number that you own or provide you with a (german +49) phone number.

In case you want to use your own phone number, we have to coordinate and find a time to activate the account together.

If you want to use your own phone number:

  • You can use land line or mobile phone numbers. Your number must be able to receive either international SMS or international calls.
  • In case of voice activation: Your phone number may NOT be behind an IVR. The IVR needs to be deactivated for the activation call.
  • If you used WhatsApp on this number before, you must deactivate the account (not delete the app!) in the App via Settings – Account – Deactivate Account
  • You must send the activation code to us, after you receive it.

Congratulations! You can now use the WhatsApp Business API!

Messages

Messages form the core of our platform: We created a simple and universal schema to describe messages sent to and received from several messaging apps and unified their fields. Messages can take multiple shapes depending on the payload they transfer.
They are a self-contained format, meaning messages carry all information required to route them or determine their current status. We will go through the individual properties below. If all you need is a quick reference, please scroll down to the bottom of the page.

The key part about the flow is that messages are sent asynchronously. We queue each message upon arrival, having a separate worker cluster in place to actually transmit them. This has multiple benefits: The API is exceptionally fast in digesting your messages because we don’t need to wait for the remote response. We’re also able to retry transmission, for example.
This means that your application will need to synchronize the status of a sent message via our incoming webhooks. The best strategy would be to have two separate processes to send messages and update them as webhooks roll in.

Routing

To send a message, we need to know the channel you intend to send it from, and the recipient the message is destined for. Since you can comfortably use an unlimited number of channels with our platform, we can’t identify the sender automatically. There are currently two ways to specify the routing details:

  • Separate properties:
    Pass the sender and recipient property in your message. This is also the format we return from the messages endpoint when retrieving existing messages and recommended due to the ease of integration.
  • Identifier shorthand:
    Due to legacy constraints, we also support the identifier shorthand field. It allows you to pass the sender and recipient as a colon-delimited string, which is arguably easier to type on the command line, but more complex to use in code. The identifier is always constructed as <Channel UUID>:<Recipient Identifier>.

In both cases, the recipient is the identifier of a user of a messaging app. For WhatsApp Business, this will be the phone number of a user, for Telegram the ID of a previous chat and the user ID for Facebook users in Messenger. For incoming messages (user responses), this will be reversed: In this case, the sender contains the user identifier, and the recipient contains the channel UUID the message is intended for.

Note that Telegram and Facebook require the user to start a conversation with your channel. You can subsequently reply to the conversation ID.

Finally, a minimum working, outgoing message looks like the following:

{
    "identifier": "<Channel UUID>:<Recipient ID>",
    "payload" : {
        "text": "This is an example message"
    }
}

A user response will look like so:

{
    "identifier": "<Recipient ID>:<Channel UUID>",
    "payload" : {
        "text": "This is an example response"
    }
}
Message payloads

The payload is the actual content of your message. In ye olden days, you would send SMS messages with plain text content only, but it’s 2020 now, so there’s a plethora of available formats to send your content in! We’ve unified the different offerings into a range of reusable and compatible payload types for you to choose from. You can find these in the format reference at the bottom of this page.
Basically, you can choose from sending text messages, media attachments (images, audio files, videos, documents, files etc.), contacts, locations, interactive buttons or template messages. The following sections describe them in greater detail.

Attachments

You can send multiple different media types to all messaging platforms, even though the supported MIME types vary across platforms. You can find a detailed list at the bottom of this section.
All attachments will be sent the same way: By adding the attachment property to the message payload and specifying a payload type of the media type you’re trying to send. The attachment will be included in the message, regardless of the media type.

{
    "identifier": "<Recipient ID>:<Channel UUID>",
    "payload" : {
        "type": "image",
        "text": "This is an optional caption",
        "attachment": "<Attachment UUID>"
    }
}
Supported formats for specific media types

The following (non-exhaustive) list of media types will be detected as images, audio files or video, respectively. Other types will be sent as documents without a preview.

Format WhatsApp Telegram Facebook Messenger
image/jpg
image/png
image/gif
audio/mpeg
audio/aac
audio/mp4
audio/ogg ✓¹
video/mp4
video/3gpp

¹: Only as audio/ogg; codecs=opus specifically.

Message Templates / Notifications

Note: Message templates currently only work in WhatsApp Business

If you want to send a message outside of a 24h window, you must send a previously approved message template. You can create templates under Settings -> Templates.
After you submit these templates for review, it takes around 24 – 72h for the templates to be approved, also dependent on the language of the template.

Important:

  • Make sure to follow the messaging guidelines: developers.facebook.com/docs/whatsapp/message-templates/guidelines
  • You need a proper Opt-In to be allowed to send an HSM.
  • Every language must have the same amount of variables / placeholders.
  • This kind of message cannot include an attachment, only text. This will probably change “soon”.

The payload for a message template or “HSM” (Highly Structured Message) looks like this:

{
    "identifier": "<UUID>:<RecipientId>",
    "payload" : {
        "type": "template",
        "template": {
            "type": "notification",
            "notification": {
                "name": "name_of_the_template",
                "language": "en",
                "params": 
                    [
                        "variable1", 
                        "variable2", 
                        "..."
                    ],
                "ttl": 86400    
            }
        }
    }
}

The minimum payload for a notification without variables / placeholders that is sent in english looks like this:

{
    "identifier": "<UUID>:<RecipientId>",
    "payload" : {
        "type": "template",
        "template": {
            "type": "notification",
            "notification": {
                "name": "name_of_the_template",
                "language": "en"    
            }
        }
    }
}
Buttons

Note: Buttons currently only work on Facebook Messenger and Telegram.

We allow up to 3 Buttons for Facebook or Telegram. When a user clicks on a button, you will receive the message as if it were a text message, so it’s best to use indicators that you can easily discern from user messages. For example, it’s better to use __unsubscribe than stop as the button payload.

Buttons

{
    "type": "url",
    "payload": "url",
    "caption": "string"
}

Button type “url” requires a valid URL:

{
    "identifier": "FB-Page-Name:RecipientId",
    "payload" : {
        "text": "This is an example message",
        "buttons": [
            {
                "type": "url",
                "payload": "https://example.com",
                "caption": "Button-Text"
            },
            {
                "type": "text",
                "payload": "__unsubscribe",
                "caption": "Unsubscribe"
            }
        ]
    }
}
Message Splitting

If a message is too long or can otherwise not be sent in a single call, we will split the message for you.

Examples:

  • Facebook cannot send images and text in a single message
  • Maximum length of text exceeded
  • WhatsApp cannot send documents or audio files and text

In these cases the payload might look like this:

{
    "id": "abcdef12-1234-abcd-4321-654321abcdef",
    "messenger": "FB",
    "split": true,
    "message_amount": 2,
    "status": "queued"
}
Message Format Reference

The following table describes all fields of the message object. Please note that some fields are not settable when sending messages but will be populated in webhooks or while retrieving them from the API.

Field Type Description
sender string Sender of this message. Only required if no identifier present.
recipient string Recipient of this message. Only required if no identifier present.
identifier string Sender and recipient as a colon-separated string, as in <sender>:<recipient>.
payload object Message payload. Always required. Fields are described below.
uuid string Unique message identifier that can be used to reference the message later on.
messenger_id string Message ID as reported by the messaging app. Mostly relevant for debugging.
messenger string Name of the messenger this message was sent to or received from.
outgoing boolean Whether this message is outgoing or incoming.
statuscode int HTTP status code as received from the messaging app for outgoing messages, status code received from the webhook (if configured) for incoming.
webhook_request string Full request body sent to webhooks. Deprecated: We will soon offer an endpoint to review all webhook requests instead. The field will not be included anymore from version 2 onwards.
result string Full response body received from the messenger app for outgoing messages, body received from the webhook (if configured) for incoming. Deprecated: We will soon offer an endpoint to review all webhook requests instead. The field will not be included anymore from version 2 onwards.
created string ISO-8601 date this message was persisted to our backend.
processed string ISO-8601 date this message was processed by our worker cluster.
sent string ISO-8601 date this message was sent by our worker cluster (outgoing) or sent by a user device (incoming).
received string ISO-8601 date this message was received by our worker cluster (incoming) or received by a user device (outgoing). Might not be reported depending on user device configuration.
read string ISO-8601 date this message was read by a human recipient. Might not be reported depending on user device configuration.
Payload Format Reference

As previously mentioned, the payload object is pretty flexible and can take many shapes as appropriate for the content transmitted. The following table describes all fields, but not every possible combination is valid – you cannot send a text message with an attachment, for example. Please review the example messages above for usage information.

Field Type Description
type string Message type. See below for a list of possible message types.
text string Text of the message for text messages or caption for attachments. We do not apply any post-processing to the message text.
template object Template message data. Can only be used in template payloads.
attachment string UUID of the attachment. This goes both ways: For incoming messages, you can use the UUID to download the file, while you can use it to specify a specific attachment to add to the message.
latitude string Latitude for location payloads. The field will not be included for other message payload types.
longitude string Longitude for location payloads. The field will not be included for other message payload types.
postback string Postback content as reported by the messaging platform. Currently, only Facebook Messenger supports postback, but that might change with the introduction of buttons in other messaging apps.
status object Status changes. This field will only be available in status updates sent to your webhook.
buttons array Buttons to attach to the message. Check out the buttons section for information on how to add buttons.
buttons[].type string Button type. Either text or url. Text buttons trigger a response with the button payload, URL buttons open the given payload URL in the user browser.
buttons[].payload string Button payload. For URL buttons, this must be a valid URL that the user can open in their browser by clicking the button. For text buttons, this will be the message text you receive as a response.
buttons[].caption string Button caption. This is the label text shown on the button
user object Information about the user who sent a message. This will only be set on incoming messages.
user.id string ID of a user as reported by the messaging app. For WhatsApp users, this will be the phone number.
user.name string Name of a user as reported by the messaging app.
user.image string URL to the profile image of a user as reported by the messaging app. Note that this property will be NULL if we don’t receive any image from the messaging app, which depends heavily on user settings.
timestamp string Original timestamp of a message as reported by the messaging app.
meta object Key-Value map of user-defined meta data for a message. You can use this object to attach arbitrary data to a message which we will not modify. This is especially useful to add custom user references or conversation IDs to messages for later retrieval.
split_message number In some cases, a message must be split into multiple messages, for example if the payload text is too long or a messaging app doesn’t support attachment captions. If a message has been split into multiple payloads, this field allows to keep track of the position in relation to the other payloads. If the message has not been split, this field will be NULL.
Payload types

A message payload always has a type, which basically describes what it contains. The type is very practical to determine how to handle a message. The following values are available:

  • text
    Text payloads only contain the message text. This is a text only chat message.
  • template
    This payload type describes notification templates as used in the WhatsApp Business API.
  • system
    System messages are events emitted by the messaging platform itself, for example when someone joins a group or edits its title.
  • image
    Image payloads contain an image attachment and optionally a caption.
  • audio
    Audio payloads contain an audio recording or voice message attachment and optionally a caption.
  • video
    Video payloads contain a video attachment and optionally a caption.
  • document
    Document payloads contain an arbitrary attachment and optionally a caption. Different platforms support a different subset of file types, so anything not image, audio or video will be transmitted as a document message.
  • contact
    Contact payloads contain information about a contact. This will currently be a JSON-encoded string, as we currently don’t parse contact information, but we plan to support unified contact data if our customers show interest in such a feature.
  • location
    Location payloads contain information about a geological location, represented by coordinates to a point on the map.
  • postback
    So-called Postback messages are triggered in response to a user pressing a button in a previous message. By listening for the postback, you can implement simple decision trees.
  • unknown
    This is the default type for a payload without an explicitly set type or when the type cannot be determined automatically. While you can omit the type in some cases, we strongly encourage you to add it to all requests.

Webhooks

Webhooks are a versatile tool to get notified about incoming messages. In essence, they allow you to subscribe to a
certain event and be notified as soon as something happens: Our servers will dispatch a highly configurable HTTP
request to your application, containing many details about the message.
Webhooks exist as free-standing entities. This means that you don’t have to configure a specific webhook for each
channel but rather route a channel to an existing webhook. This allows for exciting routing configurations, like
having a webhook for multiple messenger channels or a single one for each.

How does it work?

As soon as a message (both incoming and outgoing) arrives, we check the configured destination. This might be a channel
or a webhook. If the configuration points to a webhook, we create a JSON representation and attempt to send a request
to your webserver. In case it doesn’t return a status code in the 200 range, we will log the incidence and send an email
notification to all addresses provided by you.

Please make sure that your webhook endpoint takes no longer than 2 seconds to send a reply. Our webhooks workers
are configured to time out after that and consider the webhook request failed, consequently setting the delivery
status to 408 Request Timeout.
We need to do this to ensure individual webhooks are not blocking our delivery infrastructure for too long.

Making sure requests are legitimate

So you’ve got a webserver endpoint exposed to the world. How do you make sure this isn’t someone with a malicious
intent, trying to inject messages into your system?
To prevent this, we have implemented several measures to make it harder for an attacker to abuse your webhooks. First of
all, you should make sure to keep the URL unguessable: Using something like /webhooks/<UUID> works fine, for example.
Additionally, you can configure a secret for each webhook. The secret will be sent as a Bearer token in the
Authorization header of the webhook requests. This acts as a simple password system where you may check any incoming
requests for the correct token.

Due to the nature of our cluster, we cannot provide you with a list of IP addresses to whitelist.

Webhook verification

On creating a webhook, we request you to verify the webhook. This is a security measure that benefits both you and us:
It makes sure the URL you provided actually points to a valid webhook intended to receive messages from our servers.
The verification process works like so:

  1. We send an initial HTTP request to the webhook URL you provided. It contains a JSON object with two properties:
    verification_token and challenge. The verification token is an arbitrary value chosen by you during the webhook
    creation; the challenge is a random string generated by our servers.
  2. You check the verification token: This should be a value hard-coded in your application code. If the token matches
    the one in your code, the request did indeed originate from our servers, since the token is only known to you and
    us.
  3. You send a response with status code 200 and a JSON object in the request body that contains a single property:
    challenge. This property must contain the challenge you received from our servers.

If all goes well, the webhook is verified and ready to be connected to a channel!

Note: We might repeat this verification process at times to make sure the configuration is still correct. Please make
sure you keep the required code parts in your application.

We have an example webhook implementation prepared here.

DpaSettings

Get Example Dpa Contract
No description available
GET/exampledpacontract
Parameters

This method has no parameters

Get Dpa Settings
No description available
GET/settings/dpa
Parameters

This method has no parameters

Get Dpa Contract
No description available
GET/settings/dpa/contract
Parameters

This method has no parameters

Get Example Dpa Contract
No description available
GET/settings/dpa/example
Parameters

This method has no parameters

Media

Create

Upload a media file. As the flow of messaging is inherently asynchronous, you will need to persist your files
before you can send them. This allows you to specify a previously uploaded file by simply passing its ID when
sending a message: You can reuse any file you’ve sent previously.

Uploading files works by passing the file blob as the request body and setting the Content-Type header to the
MIME type of your file. For security reasons, we use machine learning algorithms to check every uploaded file for
whether it matches the provided content type, so please make sure the type matches the file.

POST/media
Parameters
NAME VALUE TYPES DESCRIPTION
file binary

The media file to upload as a blob. The file MIME type must be passed in the Content-Type header.

Index

Retrieves all media files

GET/media
Parameters

This method has no parameters

Single

Retrieves a single media file. Please download the files and do not reference them directly.We will delete media on our servers after 60 days.

GET/media/{uuid}
Parameters
NAME VALUE TYPES DESCRIPTION
uuid string

Media UUID

Delete

Deletes a media file

DELETE/media/{uuid}
Parameters
NAME VALUE TYPES DESCRIPTION
uuid string

Media UUID

Download

Downloads a single media file

GET/media/{uuid}/download
Parameters
NAME VALUE TYPES DESCRIPTION
uuid string

Media UUID

Feedback

Create

Creates a new feedback message

POST/feedback
Parameters

This method has no parameters

News

Get Notifications

Retrieves the latest notifications for your account

GET/notifications/
Parameters

This method has no parameters

Update Notification

Mark a notification as read

PUT/notifications/{uuid}
Parameters
NAME VALUE TYPES DESCRIPTION
uuid No description available

Get Change log

Retrieves the latest changelog entries for your account

GET/changelog/
Parameters

This method has no parameters

Billing

Get Payments

Retrieves all payments

GET/billing/payments
Parameters

This method has no parameters

Get Single Payment

Retrieves a single payment by ID

GET/billing/payments/{id}
Parameters
NAME VALUE TYPES DESCRIPTION
id string

The payment ID

Get Invoices

Retrieves all invoices

GET/billing/invoices
Parameters

This method has no parameters

Get Single Invoice

Retrieves a single invoice by ID

GET/billing/invoices/{id}
Parameters
NAME VALUE TYPES DESCRIPTION
id string

The invoice ID

Messages

Send

Sends a message

POST/messages
Parameters
NAME VALUE TYPES DESCRIPTION
identifier string

Identifier <channel-uuid>:<recipient> Message Documentation

payload object

Message payload

Index

Retrieves all messages, newest messages first

GET/messages
Parameters
NAME VALUE TYPES DESCRIPTION
limit integer

Amount of messages

offset integer

Skip this amount of messages

sort string

Fields to sort by. This allows multiple sorts as field:direction, so sorting by sender descending, then by recipient would be sender:desc,recipient:asc.

filter string

Filters to apply. This allows complex filter expressions as field-operator-value and multiple filters joined by comma. Read the
filtering section for more information.

query string

Search query to search for. Includes sender, recipient and messenger ID.

recipient string

Only show messages with this recipient (Deprecated: Use the filter parameter instead).

sender string

Only show messages with this sender (Deprecated: Use the filter parameter instead).

outgoing boolean

Only show outgoing (true / 1) or incoming (false / 0) messages or don’t submit this parameter or set it to “both” for both directions. (Deprecated: Use the
filter parameter instead
).

Single

Retrieves a single message

GET/messages/{uuid}
Parameters
NAME VALUE TYPES DESCRIPTION
test string

this is a param

uuid No description available

Delete

Delete a single message (Remove all its content, but keep the line in the database for statistics and invoicing)

DELETE/messages/{uuid}
Parameters
NAME VALUE TYPES DESCRIPTION
uuid No description available

Channels

Get All Channels

Retrieves all channel configurations

GET/channels
Parameters

This method has no parameters

Get Single Channel

Retrieves a single channel

GET/channels/{uuid:.{36}}
Parameters
NAME VALUE TYPES DESCRIPTION
uuid string (uuid)

Channel UUID

Telegram

Index

Retrieves all Telegram channel configurations

GET/channels/telegram
Parameters

This method has no parameters

Create

Adds a Telegram Channel## How to create a Telegram-Bot

  1. Install Telegram on your phone
  2. Open Telegram Web (https://web.telegram.org) and search for the User “@BotFather” Direct link to BotFather Chat
  3. In the chat window, type /start or click the Start-Button to see a list of possible commands
  4. Write “/newbot” and send the chat to @BotFather
  5. Select a name for your Bot
  6. Select a username for your bot. The username must end with the letters “bot”.
  7. The @BotFather will now show you a token. Copy the whole token (number:string) and paste it here https://app.messengerpeople.dev/channels/telegram/create (Menu -> Channels -> Telegram -> Click + Button) or POST it to /channels/telegram
  8. If the token is correct, then your bot is now active and connected to your Account.
Example

This is not a real token of course, but the token you will receive is likely to look similar:

Add a Telegram Bot

POST/channels/telegram
Parameters
NAME VALUE TYPES DESCRIPTION
bot_token string

Telegram bot token

webhook string

UUID of the webhook to use. Leave empty to not receive webhooks.

Update Telegram Channel

Updates a Telegram channel. This allows to assign a new webhook.

PUT/channels/telegram/{uuid}
Parameters
NAME VALUE TYPES DESCRIPTION
webhook string

UUID of the webhook to use. Leave empty to disable webhooks reception.

billing string

Choose ppm or mau to switch between “pay per message” or “monthly active user”. Leave blank if you don’t want to change the billing
method.

uuid string

UUID of the channel

Facebook Messenger

Index

Retrieves all Facebook Messenger channel configurations

GET/channels/facebook-messenger
Parameters

This method has no parameters

Create

Adds a Facebook Messenger Channel. Please us the frontend under app.messengerpeople.dev to connect your
Facebook Pages.

POST/channels/facebook-messenger
Parameters

This method has no parameters

Update Facebook channel

Updates a facebook channel. This allows to assign a new webhook.

PUT/channels/facebook-messenger/{uuid}
Parameters
NAME VALUE TYPES DESCRIPTION
webhook string

UUID of the webhook to use. Leave empty to disable webhooks reception.

billing string

Choose ppm or mau to switch between “pay per message” or “monthly active user”. Leave blank if you don’t want to change the billing
method.

uuid string

UUID of the channel

WhatsApp

Index

Retrieves all WhatsApp Business channels

GET/channels/whatsapp-business
Parameters

This method has no parameters

Create

Adds a WhatsApp Business channel. Please use the frontend under app.messengerpeople.dev to add a WhatsApp
Business Channel.

POST/channels/whatsapp-business
Parameters

This method has no parameters

Update Whats App Business channel

Updates a WhatsApp Business channel. This allows to assign a new webhook.

PUT/channels/whatsapp-business/{uuid}
Parameters
NAME VALUE TYPES DESCRIPTION
webhook string

UUID of the webhook to use. Leave empty to disable webhooks reception.

billing string

Choose ppm or mau to switch between “pay per message” or “monthly active user”. Leave blank if you don’t want to change the billing
method.

uuid string

UUID of the channel

Custom Channels

Index

Retrieves all custom channels

GET/channels/custom
Parameters

This method has no parameters

Create

Creates a new custom channel

POST/channels/custom
Parameters
NAME VALUE TYPES DESCRIPTION
name string

Display name of the custom channel

url string

Listener URL to dispatch outgoing messages to. Must be an HTTPS endpoint.

secret string

Optional secret to send as an Authorization: Bearer {{secret}} header.

Single

Retrieves a single channel

GET/channels/custom/{uuid}
Parameters
NAME VALUE TYPES DESCRIPTION
uuid string

Custom channel UUID

Update

Updates a custom channel

PUT/channels/custom/{uuid}
Parameters
NAME VALUE TYPES DESCRIPTION
name string

Display name of the custom channel

url string

Listener URL to dispatch outgoing messages to. Must be an HTTPS endpoint.

secret string

Optional secret to send as an Authorization: Bearer {{secret}} header.

uuid string

Custom channel UUID

Settings

Get Customer Settings

Retrieves the customer settings

GET/settings/customer
Parameters

This method has no parameters

Update Customer Settings

Updates customer settings

PUT/settings/customer
Parameters
NAME VALUE TYPES DESCRIPTION
name string

Name of the customer (Company / Person)

vat_id string

Customer VAT ID, if applicable

payment_threshold integer

Prepaid bottom threshold value. If the credit falls below this threshold, a payment will be triggered to recharge the credit.

payment_amount integer

Prepaid amount to recharge the credit with.

name_given string

Customer given name

name_family string

Customer family name

company string

Customer company name, if applicable

street string

Customer street address

zip string

Customer ZIP code

city string

Customer city name

country string

Customer country name

state string

Customer state

email string (email)

Customer email address

payment_method string

Selected payment method

Patch Customer Settings

Updates customer settings

PATCH/settings/customer
Parameters
NAME VALUE TYPES DESCRIPTION
name string

Name of the customer (Company / Person)

vat_id string

Customer VAT ID, if applicable

last_seen_changelog integer

Last seen changelog item ID

Credit Card Settings

Add Credit Card

Adds a credit card

POST/settings/creditcards
Parameters

This method has no parameters

Get Credit Cards

Retrieves all credit cards

GET/settings/creditcards
Parameters

This method has no parameters

Confirm Credit Card

Confirms a credit card

GET/settings/creditcards/confirm
Parameters

This method has no parameters

Statistics

Get Message Statistics
No description available
GET/statistics/messages
Parameters

This method has no parameters

Get Message Statistics For Channel
No description available
GET/statistics/messages/{uuid}
Parameters
NAME VALUE TYPES DESCRIPTION
uuid No description available

Get Media Statistics

Retrieves media statistics

GET/statistics/media
Parameters

This method has no parameters

Get Costs Statistics

Retrieves cost statistics

GET/statistics/costs
Parameters

This method has no parameters

Template

Add Template

Adds a new template

POST/templates
Parameters
NAME VALUE TYPES DESCRIPTION
name string

Template name

category string

Template category

waba_id string

Template waba_id

translations array

Optional list of template translations as a language -> translation map

Get Templates

Retrieves all templates

GET/templates
Parameters

This method has no parameters

Get Template Categories

Lists all available template categories

GET/templates/categories
Parameters

This method has no parameters

Get Template Languages

Lists all available template languages

GET/templates/languages
Parameters

This method has no parameters

Get Waba Ids

Returns all WABA IDs and the corresponding WhatsApp Business Accounts

GET/templates/waba-ids
Parameters

This method has no parameters

Get Template

Important: All fields must be set, including at least one website, or all input will be ignored.

GET/templates/{uuid}
Parameters
NAME VALUE TYPES DESCRIPTION
uuid string

Template UUID

Update Template

Updates a template

PUT/templates/{uuid}
Parameters
NAME VALUE TYPES DESCRIPTION
uuid string

Template UUID

Delete Template

Deletes a template

DELETE/templates/{uuid}
Parameters
NAME VALUE TYPES DESCRIPTION
uuid string

Template UUID

Submit For Review

Submits a template for the review

PUT/templates/{uuid}/review
Parameters
NAME VALUE TYPES DESCRIPTION
uuid string

Template UUID

Webhook

Add Webhook

Creates a new webhook.

POST/webhooks
Parameters
NAME VALUE TYPES DESCRIPTION
name string

Display name for the webhook

url string

Webhook URL. The URL must be valid and point to your working application. Please refer to the webhook documentation for details on
the webhook verification process.

active boolean

Whether the webhook is enabled

secret string

Optional secret to be sent in the Authorization header each time the webhook is called.

verification_token string

Verification token for the initial webhook verification challenge. The token must be between 8 and 32 characters in length.

notification_recipients undetermined

List of valid email addresses to send webhook failure notifications to. The notifications will be batched, so in case your webhook fails, you
won’t be buried in emails 😃

status_messages boolean

Whether to send status updates (read / delivered / sent) to this webhook

Get Webhooks

Retrieves all webhooks

GET/webhooks
Parameters

This method has no parameters

Get Webhook

Retrieves a single webhook

GET/webhooks/{uuid}
Parameters
NAME VALUE TYPES DESCRIPTION
uuid string

UUID of the webhook to delete

Update Webhook

Updates an existing webhook

PUT/webhooks/{uuid}
Parameters
NAME VALUE TYPES DESCRIPTION
name string

Display name for the webhook

url string

Webhook URL. The URL must be valid and point to your working application. Please refer to the webhook documentation for details on
the webhook verification process.

active boolean

Whether the webhook is enabled

status_messages boolean

Whether to send status updates (read / delivered / sent) to this webhook

secret string

Optional secret to be sent in the Authorization header each time the webhook is called.

verification_token string

Verification token for the initial webhook verification challenge. The token must be between 8 and 32 characters in length.

notification_recipients undetermined

List of valid email addresses to send webhook failure notifications to. The notifications will be batched, so in case your webhook fails, you
won’t be buried in emails 😃

uuid string

UUID of the webhook to update

Delete Webhook

Deletes a webhook

DELETE/webhooks/{uuid}
Parameters
NAME VALUE TYPES DESCRIPTION
uuid string

UUID of the webhook to delete

Whatsapp Business

Get Groups

Important: All fields must be set, including at least one website, or all input will be ignored.

GET/whatsapp-business/groups/{uuid}
Parameters
NAME VALUE TYPES DESCRIPTION
uuid No description available

Create Group

Creates a group

POST/whatsapp-business/groups/{uuid}
Parameters
NAME VALUE TYPES DESCRIPTION
subject string

The subject or title of the group

uuid string

WhatsApp Business phone number or UUID of the Channel

Add Group Admins

Adds group administrators

POST/whatsapp-business/groups/{uuid}/addAdmins
Parameters
NAME VALUE TYPES DESCRIPTION
group_id string

ID of the group to add the administrator to

phone_nr string

Phone number of the new group administrator

uuid string

UUID of the channel

Get Settings

Retrieves the current WhatsApp business settings

GET/whatsapp-business/profile/{uuid}
Parameters
NAME VALUE TYPES DESCRIPTION
uuid string

UUID of the channel

Update Settings

Important: All fields must be set, including at least one
website, or all input will be ignored.

PUT/whatsapp-business/profile/{uuid}
Parameters
NAME VALUE TYPES DESCRIPTION
about string

The ‘About’ section, or the ‘old status’: ‘Hey there, i’m using WhatsApp’.

profile array

Required fields: address, description, email, vertical, websites (array). ‘websites’ must contain at least one valid domain (https://…) and a maximum of two
domains.

uuid string

UUID or phone number of the WB account you want to edit

Get Picture

Retrieves the profile image

GET/whatsapp-business/picture/{uuid}
Parameters
NAME VALUE TYPES DESCRIPTION
uuid No description available

Update Picture

Updates the WhatsApp profile picture

PUT/whatsapp-business/picture/{uuid}
Parameters
NAME VALUE TYPES DESCRIPTION
$uuid string

UUID of the WhatsApp Business Account to set the profile picture for

uuid No description available

Monitoring

Get All Calls
No description available
GET/monitoring/calls
Parameters

This method has no parameters

Get Error Calls

Retrieves all failed calls

GET/monitoring/calls/errors
Parameters

This method has no parameters

Get Calls By Status

Retrieves all messenger API calls by HTTP response status code

GET/monitoring/calls/status/{code:\d+}
Parameters
NAME VALUE TYPES DESCRIPTION
limit integer

Result pagination limit

offset integer

Result pagination offset

code integer

HTTP status code to filter for