Standard Service Offering

This was @dmccann’s proposal. I think the reasoning is that it’s generally easier to implement a synchronous API, though async delivery reporting does better match the underlying protocols.

I’m happy to drop Sync and move Async into Core.

@dmccann what do you think?

I think this would be a pretty edge case where, for example, you want to hand-build a message in a unique encoding (‘artisanal’ sms). I’d be happy to drop this unless there is an outcry,.

1 Like

@smn Can you propose a set of monitoring/health/heartbeat functions you’d like to see in core?

This makes sense to me–though I see some utility of having a multi-channel “base” or standard of some sort. Specifically in making it easy to explain and market to less technical customers.

Maybe we define ‘core, recommended, advanced’ per category (SMS, Voice, USSD, Payments etc…) and also consider defining standard ‘bundles’ e.g. “communications service bundle” ?

@muratk the motivation for an API is to enable user-level applications to provide cost/volume estimates to the end-user.

These apps can of course include their own encoding & splitting logic, but that creates the possibility that the API provider and app count messages differently creating error.

It’s a bit like the “price-the-cart” problem where it’s best to have a single code path.

For example, I’ve seen some SMS systems use a simple logic for charset encoding and CSM calculation as follows:

  • try to encode message buffer in GSM 03.38
  • If succeeds, divide number of characters by 160 to determine number of SMSs
  • If fails, divide number of chars by 70 to determine number of SMSs

But a more sophisticated system would encode each individual message in a CSM as efficiently as possible, so that if a non-GSM char appeared once, say in the first 70 chars, the first message would be Unicode encoded, but the rest of the buffer would go as GSM.

If the underlying service provider uses one approach and the app another, counts will be off.

@muratk I think you caught a typo here. I believe we meant text-to-speech, not speech-to-text. @dmccann can you confirm?

Of course your question on languages still applies.

My gut would be to leave the specific languages out of any proposed standard, and maybe simply say something like “Text-to-Speech for 1+ languages”

Of course any provider, when describing their own offering, would want to list the languages they support.

@muratk – if the most basic APIs for handling SMS/USSD/Voice conversations is some kind of callback system (like web-hooks), this would be the next level of hosted functionality where a provider can run an entire interaction without needing to call webhooks–perhaps by implementing the RapidPro Flow specification .

The idea being that clients of the API could provide in advance any necessary assets (e.g. audio files for IVR) and rules such that the provider can run the interaction and provide the results to the client.

Honestly, this might never make sense for an API provider to offer. It may be a feature that makes most sense for an app provider like engageSpark to handle at the user level.

Hence ‘advanced’

I would worry that putting this in core would have strange unintended consequences. I’ve seen aggregators implement fake (and immediate) MT delivery reports for MNOs that didn’t supply delivery reports because that’s what a contract stipulated.

I’m struggling to define a set of criteria that’s comprehensive enough to be useful as what is possible depends on the underlying protocols used. Here’s a very incomplete attempt:

  1. For protocols that implement an underlying connectivity signal, expose an API that provides a view of the last n signals received and map those to standardized indicators.

Example: SMPPs enquire_link PDU is sent at regular intervals. An API should be able to map this to a standardised indicator that represents an established connection.

  1. For protocols that implement a stateful connection, expose an API that maps the state of the connection to a standardised indicator.

Example: An SMPP connection being bound in rx, tx, or trx mode can be mapped to indicators that indicate that the authentication has succeeded. Absence of it means a disconnection.

  1. For systems that relying on internal queing, expose an API that gives insight into queue sizes and growth / drain rates. Junebug provides some support for this.

  2. For stateless connections (which most USSD protocols are) provide an API that the succes rate of n most recent USSD replies (if the protocol is asynchronous) and the n most recent USSD requests received.

I think my “app developer” bias was probably showing here. I don’t have a strong preference as to which (sync or async) lives where. My concern would more be that at least some form of delivery reporting is available in core.

My reasoning here was to assume that the application developer:

  1. Wants to be able to collect user input via speech or DTMF
  2. Lacks the sophistication to have either voice synthesis or recognition built into their app (might be dubious, that’s why this is only in recommended rather than core).

Since there’s a low-tech workaround for text-to-speech (pre-recorded humans), I felt like only speech-to-text needed to be here.

What do people think about the above, especially #2?

I think text-to-speech is a basic feature of all the headless-IVR systems. It’s easy to implement and useful. I wouldn’t leave it out.

Speech-to-text is pretty advanced stuff, and does have a workaround–record the speech and send the file to a transcription (machine or human) service :wink:

If we keep speech-to-text, I’d argue for moving it to ‘advanced’

I’ll adjust based on @smn’s suggestion

1 Like

Provided the response isn’t being used in your branching logic, of course! :stuck_out_tongue: Fine with moving to advanced.

Do you think it’s possible/reasonable to have a higher-level ‘monitoring’ API that provides a simplified indicator, maybe per-service or channel, of whether the service provider considers it ‘operational’ or not?

I’m thinking something like Twilio’s dashboard (and the underlying API that feeds it):
https://status.twilio.com/

I think it should be doable from an aggregator perspective as it should be able to expose whatever underlying view it has into some kind of composed view.

Expecting the aggregator to be able to give insight into upstream problems (delivery delays at MNOs for example) I would consider quite beyond the scope of core though. The problem is that some protocols, especially the stateless ones, have zero useful indicators that help distinguish between “no traffic” and “networking problems”.

Hi Jeff,

I’ve added the following comments to the google doc, as possible core components of a payment service:

  • Ability to send one or more payments to one or more mobile subscribers
  • Ability to receive a payment from a mobile subscriber
  • Subscriber verification

Hey! Thanks for your input. Would it be fair to assume that balance checking, top up, are subcomponents of being able to to send / receive payments?

Maybe we should add ‘operational status of upstream services’ to ‘Advanced’?

Thank you @Luke_Kyohere!

Sorry for the incorrect file permissions—I’ve made the sheet world-editable so you (and everyone else) can make direct changes.

In the meantime, I went ahead and converted your comments to boxes and put in some proposed language.

Please check (and correct!) that I interpreted your comments correctly. Here’s a handy link to the sheet for you.

Question: Verification
What kind of verification do you mean? Verifying that the subscriber has a mobile-money account that can receive funds? Verifying that they have sufficient balance?