API access
Your code can talk to Banga in four ways. Each has its own credentials, and only the first three are meant for apps.
Which API to use
| API | What it is for | Credentials | Read more |
|---|---|---|---|
| Webhooks | The platform calls your server when a member runs a command, submits a form, taps a card button or pays. | Signed requests you verify with your app's secret | Webhooks |
/bot-api/v1 | Post cards into rooms your app was added to. | Room bot token, bbt_... | Room bots |
/app-api/v1 | Look up payments, refund them and pay members out. | Payments key, bpk_... | Payments |
/api | The REST API the Banga apps themselves use. | A signed-in member's access token | API reference |
Tokens and keys are shown once in the developer console; only a hash of each is stored. Keep them on your server, never in a web page or a mobile app.
The REST API reference
The API reference documents every /api endpoint with its
parameters, request and response bodies and error answers. The same description is available as an OpenAPI
document at /v3/api-docs/api-traffic.
- Every call needs
Authorization: Bearer <access token>. Access tokens are short-lived and are issued only by the apps' sign-in: a phone number, an SMS code and a registered device. - There are no API keys for
/api. Never ask members for their tokens; an app gets what it needs from the platform, with the member's consent, as described under What an app can know. /apiis not versioned and changes together with the apps. Build integrations on webhooks,/bot-api/v1and/app-api/v1, which are versioned.
An example call
curl "https://dev.banga.chat/bot-api/v1/rooms/ROOM_ID/cards" \
-X POST \
-H "Authorization: Bearer bbt_..." \
-H "Content-Type: application/json" \
-d '{ "blocks": [ { "type": "title", "text": "Hello from my app" } ] }'Answers and errors for each API are listed on its own page and under Limits and errors.