Connect an unlisted provider using External API
If you just need the essentials, follow this quick path:
- Confirm your provider can send/receive via HTTP (and pick a URN type)
- Add an External API channel and paste your outbound endpoint
- Configure inbound messages using the provided inbound URL
- Test outbound + inbound with one contact
- Use channel logs to troubleshoot 400/500 errors
This approach keeps your flow logic in RapidPro.app while your system handles the provider-specific delivery.
Step-by-Step Process
Before adding the channel, confirm your provider (or your middleware) can:
- Receive outbound requests from RapidPro.app (your HTTP endpoint)
- Send inbound messages to RapidPro.app (POST to the inbound URL RapidPro.app gives you)
Also decide what URN type you’ll use for contacts (examples):
- tel (phone numbers for SMS/voice-style routing)
- mailto (email-style routing, if your system supports it)
- custom IDs (when your provider uses a non-phone identifier)
[CAPTURE: Architecture diagram showing RapidPro.app → Your Outbound Endpoint → Provider, and Provider/Middleware → RapidPro.app Inbound URL.]
- Open Workspace Settings (gear icon).
- Go to Channels and click + New channel.
- Select External API.
- Configure the outbound settings (your system endpoint), including request type (GET/POST/JSON) based on what your system expects.
- Save the channel.
[CAPTURE: “Add channel” modal showing External API selected and an outbound URL/endpoint field.]
After saving the External API channel, RapidPro.app provides an inbound URL. Your system must POST inbound messages to that URL so RapidPro.app can:
- create/update the contact (based on URN), and
- record the message in Messages/contact history, and
- trigger flows when applicable.
When you send an inbound message to the URL, RapidPro.app returns a clear response:
- Accepted → message ingested
- Rejected → response includes details about what’s wrong
[CAPTURE: Confirmation screen showing the inbound URL provided for incoming messages.]
- Send a test outbound message from a simple flow to confirm RapidPro.app can reach your endpoint.
- Send a test inbound message from your system to the inbound URL.
- Confirm the inbound message appears in RapidPro.app (Messages and the contact’s history).
[CAPTURE: A simple “Send Message” flow run + Messages tab showing the inbound message recorded on the contact.]
If outbound sending fails:
- Open the channel page in Workspace Settings → Channels.
- Check the sending log to see full request details and responses.
- Use the HTTP status code + error body to identify what to fix (auth, payload format, endpoint reachability).
[CAPTURE: Channel page showing the sending log with request/response details.]
Common Issues & Quick Fixes
Outbound messages don’t send (provider never receives requests)
Problem: Your provider/middleware never receives outbound requests from RapidPro.app.
Fix:
- Confirm your endpoint URL is correct and publicly reachable.
- Verify you selected the right request type (GET/POST/JSON) and required parameters.
- Check the channel’s sending log for HTTP status codes and error responses.
Inbound messages return 400
Problem: Your system posts inbound messages but RapidPro.app rejects them.
Fix:
- Ensure your inbound request is a POST to the provided URL.
- Verify the payload matches what the External API channel expects (fields, URN format, etc.).
- Use the error details in the 400 response to correct formatting.
Contacts get “No suitable channel found”
Problem: RapidPro.app can’t find an enabled channel that matches the contact’s address.
Fix:
- Confirm the contact has a URN that matches your channel’s URN type (e.g., a phone number for tel).
- Make sure the channel is Enabled.
Messages appear, but are linked to the wrong contact
Problem: Inbound messages are recorded, but on the wrong contact profile.
Fix:
- Ensure the URN you send in inbound messages matches the contact’s URN exactly (country code, formatting).
- Avoid mixing URN types (phone vs. Telegram ID) in one External API channel.