DOCUMENTATION

GET STARTED

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


  1. Create an account to obtain an API key and a Form ID for each contact form you want to integrate.
  2. Classify each message posted to your contact form.
  3. Handle the response. The API will classify the message as true spam or false(not spam).

Check out and download our Postman Collection



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:
  • form: (Required, string) The form identifier.
  • message: (Required, string) The text to classify as spam or not.
  • metadata: (Optional, object) Any information you want us to store with the request.

Example Payload:

{
    "form": "YOUR-FORM-ID",
    "message": "The spammy message posted to your contact form."

}

Example Request:

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

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, form value, message value, or required headers. Status code: 400.
  • Unauthorized: Returned when the authentication fails. Status code: 403.


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 anb591P-76sn1pn-850fknj


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

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).
  • form_id: (string) The form identifier related to the message.
  • metadata: (object) The optional data sent with the classify request.

Example:

{
    "status_code": 200,
    "timestamp": "2022-04-18T10:15:30Z",
    "message": "The spammy message posted to your contact form.",
    "spam": true,
    "form_id": "YOUR FORM ID",
    "metadata: {"id": 1234567, "foo": "bar"}
}

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: 403.