Documentation

Beepy | The Notification Assistant

Welcome to Beepy's the official documentation page

The Beepy API is organized around REST. Our API has predictable resource-oriented URLs, accepts json request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs. The API key you use to authenticate the request determines the request channel. The Beepy API differs for every channels as we release new versions and tailor functionality. Log in to see credentials of your channels to test and integrate.

Installation

Follow the steps below to use channel credentials

1. Login to your Beepy account or create a new account if you do not have one yet
2. Create a new channel according to your preferences. Choose one of the channel types below:
   • Public - coming soon...
   • Private - This channel type allows you to have full control of the channel and members
3. Go to Channel details page and then the Credentials Section

Authentication

The Beepy API uses API keys to authenticate requests. You can view and manage your API keys in the Beepy Dashboard. Your can find your Api key on Channel > Credentials > Api Key section

Your can find your Api key on Channel > Credentials > Api Key section

Request Header

Your apikey needs to be sent in request HEADER to authenticate your request. Authorization param should be set and the value will be your_beepy_channels_apikey. Also need to send Content-Type : application/json in your request header.

IP Whitelist

The Beepy API allows you to make ip whitelist to restrict access of channel. You can add as many ip addresses as you want to whitelist.On Channel Credentilas page to use ip whitelist section.

If you do not have any whitelisted ip address, The Beepy API allows access from anywhere

Request Params

The API requires HEADER and BODY sections to be filled properly to send notifications to Beepy channel. Request HEADER params are described on Authentication > Request Header

Below is the request structure and needs to be sent:

• title
• description
• label
  • text
  • color

Example JSON request body

{
    "title" : "AWS CloudWatch",
    "description" : "Some description about your logs, metrics etc.",
    "label" : {
        "text" : "WARNING",
        "color" : "orange"
        }
}

Example CURL request

curl -X POST https://api.beepy.io/integration/v1/notification/send \
     -H 'Content-Type: application/json' \
     -H 'Authorization: your_beepy_channel_apikey' \
     -d '{"title":"New Notification","description":"API testing notification","label":{"text":"API Tester","color":"default"}}'

Response Example

The API returns JSON-encoded responses, and uses standard HTTP response codes.

{
    "code": 200,
    "message": "Success",
    "payload": {
        "channel": {
            "guid": "channel_guid",
            "name": "My Beepy Channel",
            "slug": "my_channel_slug"
        },
        "notification": {
            "title": "A New Notification",
            "description": "My notification body.",
            "label": "INFO",
            "status": "SENT"
        },
        "delivery_status": {
            "success": 0,
            "failed": 0
        }
    }
}

Incoming Webhooks

Incoming Webhooks are a simple way to post messages from apps into Beepy Channels. Creating an Incoming Webhook gives you a unique URL to which you send a JSON payload with the message text and some options. The request parameters, title, description and label are not required.We accept all the request params as description and then put Webhook label which you have given when you create as title parameter.

Keep it secret, keep it safe. Your webhook URL contains a secret. Don't share it online, including via public version control repositories.

Request Example

curl -X POST https://api.beepy.io/integration/hook/XXXXXX/XXXXXXX/XXXXXX \
     -H 'Content-Type: application/json' \
     -d '{"title":"New Notification","description":"API testing notification","label":{"text":"API Tester","color":"default"}}'

Json Request Body

{
    "title" : "AWS CloudWatch",
    "description" : "Some description about your logs, metrics etc.",
    "label" : {
        "text" : "WARNING",
        "color" : "orange"
        }
}

Json Response Body

{
    "code": 200,
    "message": "Success",
    "payload": {
        "channel": {
            "guid": "your_channel_guid",
            "name": "My Beepy Channel",
            "slug": "my_channel_slug"
        },
        "notification": {
            "title": "A New Notification",
            "description": "My notification body.",
            "label": "INFO",
            "status": "SENT"
        },
        "delivery_status": {
            "success": 0,
            "failed": 0
        }
    }
}

Labels

Putting labels on notifications to recognise, categorise them easily. Label on the API request requires text and color params.You should choose one of the color param. If color param is not correct or set, label will be set with default color.

• Label default
• Label red
• Label green
• Label blue
• Label yellow
• Label deep_blue
• Label space_gray
• Label gray
• Label orange
• Label lavender
• Label rose
• Label deep_green
• Label aqua

Errors

Beepy uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.). Codes in the 5xx range indicate an error with Beepy's servers (these are rare).

Http Status Codes

• 200 - OK - Everything worked as expected.
• 400 - Bad Request - The request was unacceptable,missing a required parameter.
• 401 - Unauthorized - No valid API key provided.
• 402 - Request Failed - The parameters were valid but the request failed.
• 403 - Forbidden - The API key doesn't have permissions to perform the request.
• 404 - Not Found - The requested resource doesn't exist.
• 409 - Conflict - The request conflicts with another request.
• 429 - Too Many Requests - Too many requests hit the API too quickly.
• 500, 502, 503, 504 - Server Errors - Something went wrong.

Error Codes

API error responses return with code and message parameters

• 1000 - Request header requires Authorization.
• 1001 - Request header requires 'Content-Type':'application/json' to be set in request header.
• 1002 - Apikey is not valid.
• 1003 - Apikey is not active.
• 1004 - The channel is not active.
• 2001 - Webhook is not valid.
• 2002 - Webhook is not active.
• 3000 - You have reached to maximum notification limits of the month. Please upgrade your account to send as many request as you need.
• 3001 - This requester ip address is blacklisted for a reason. Please contact us for further information.

Changelog

See what's new added, changed, fixed, improved or updated in the latest versions.

Version 1.0 (01 Feb, 2022)

Initial Release