GET STARTED CLASSIFY MESSAGE GET MESSAGE

DOCUMENTATION

GET STARTED

To get started with the Bot Butcher API, follow these simple steps:

Create an account to obtain an API key.
Classify each message posted to your contact form(s).
Handle the response. The API will classify the message as true (spam) or false(not spam).

CLASSIFY A MESSAGE

Detects if a given message is spam or not.

Base URL: https://api.botbutcher.com

Method: POST

Making a Request

Required Headers:

x-api-key: (Required) API key to authenticate the request.

JSON Payload:

message: (Required, string) The text to classify as spam or not.
domain: (Optional, string) the root domain where the contact form is located (boosts accuracy).
metadata: (Optional, object) Any information you want us to store with the request.

Example Payload:

{
    "message": "The spammy message posted to your contact form.",
    "domain": "my-business-website.com"
}

Example Request:

    curl -X POST \
         -H 'Content-Type: application/json' \
         -H 'x-api-key: YOUR-API-KEY' \
         -d '{"message": "The spammy message posted to your contact form.", "domain": "my-business-website.com"}' \
         'https://api.botbutcher.com'

    import requests

    headers = {
        'Content-Type': 'application/json',
        'x-api-key': 'YOUR-API-KEY'
    }

    data = {
        'message': 'The spammy message posted to your contact form.',
        'domain": "my-business-website.com'
    }

    response = requests.post('https://api.botbutcher.com', json=data, headers=headers)
    print(response.json())

    const xhr = new XMLHttpRequest();
    const data = JSON.stringify({
        message: 'The spammy message posted to your contact form.',
        domain: 'my-business-website.com'
    });
    xhr.open('POST', 'https://api.botbutcher.com');
    xhr.setRequestHeader('Content-Type', 'application/json');
    xhr.setRequestHeader('x-api-key', 'YOUR-API-KEY');
    xhr.send(data);
    xhr.onload = function() {
        if (xhr.status === 200) {
            console.log(JSON.parse(xhr.responseText));
        }
};

Response

spam: (boolean) Indicates if the message is classified as spam (true) or not (false).
message_id: (string) A unique identifier for the message.
status_code: (integer) HTTP status code indicating the success or failure of the request.

Example Response:

{
    "spam": true,
    "message_id": "2383k0f-s5cPjaQBi1-87s10"
    "status_code": 200
}

Error Responses

Malformed request: Returned when there's a missing JSON payload value, or required headers. Status code: 400.
Unauthorized: Returned when the authentication fails. Status code: 401.

If a domain is supplied in the request that is not a valid domain an additional "notes" array will be returned in the response with any error messages such as "invalid domain". If a domain is invalid a classification will still occur but with less accuracy.

GET A MESSAGE

Retrieve any message previously sent by the message_id

Base URL: https://api.botbutcher.com

Endpoint: /message/<message_id>

Method: GET

Allows user to retrieve a Message object by its unique identifier.

Request

Headers:

x-api-key: (Required) API key to authenticate the request.

URL Parameters:

message_id: (Required, string) The unique identifier of the message to be retrieved.

Example Request:

In this example we want to retrieve message with a message_id of 8anb591P-76sn1pn-850fknj

    curl -X GET \
         -H 'x-api-key: YOUR-API-KEY' \
         'https://api.botbutcher.com/message/8anb591P-76sn1pn-850fknj'

    import requests

    headers = {
        'x-api-key': 'YOUR-API-KEY'
    }

    response = requests.get('https://api.botbutcher.com/message/8anb591P-76sn1pn-850fknj', headers=headers)
    print(response.json())

    const xhr = new XMLHttpRequest();
    xhr.open('GET', 'https://api.botbutcher.com/message/8anb591P-76sn1pn-850fknj');
    xhr.setRequestHeader('x-api-key', 'YOUR-API-KEY');
    xhr.send();
    xhr.onload = function() {
        if (xhr.status === 200) {
            console.log(JSON.parse(xhr.responseText));
        }
    };

Response

status_code: (integer) HTTP status code indicating the success or failure of the request.
timestamp: (string) The ISO 8601 format timestamp representing when the message was created.
message: (string) The text content of the message.
spam: (boolean) Indicates if the message is classified as spam (true) or not (false).
domain: (string) The root domain where the contact form exists (when provided).
metadata: (object) The optional data sent with the classify request (when provided).

Example:

{
    "status_code": 200,
    "timestamp": "2022-04-18T10:15:30Z",
    "message": "I want to schedule an appointment to fix my car. Please call me.",
    "spam": false,
    "domain": "local-car-dealership.com"
    "metadata: {"repair-order": 1234567, "phone": "+13105555555"}
}

Error Responses

Malformed request: Returned when there's a missing message_id, unknown message_id, or required headers. Status code: 400.
Unauthorized: Returned when the authentication fails. Status code: 401.