POST /secure/send with a binary transport: the same login, the same fields,
the same rating and charge, the same sender ID and template approval, the same routing check,
client_ref retry rule and per-account rate limit. Once accepted, a message sent over gRPC is
indistinguishable from one sent over REST.
It adds one thing REST does not have: a receipt feed. Ask for receipts without giving a webhook
and they wait for you in a durable queue you read over the same connection — no endpoint of your own
to run.
gRPC is off unless your provider turns it on. A gateway that has not been configured for it
answers every call
UNAVAILABLE with the error code GRPC_DISABLED. If you see that, the API exists
but is not enabled on the platform you are calling — ask your provider for the gRPC address.When to choose it
A request is a few dozen bytes of protobuf instead of a JSON body, and
SendStream sends many messages on
one stream without waiting for each answer. Neither changes what you are allowed to send or how fast:
REST and gRPC share your account’s messages-per-second limit, so moving traffic from one to the
other does not buy more of it.
SMPP remains the third way in, and is separate again — see Binding.
Three services
Connecting
Your provider gives you a host and port. On a gateway with nothing in front of it the port is usually 8090; behind a provider’s TLS proxy it is often 443.
gRPC needs HTTP/2 all the way. If calls fail at the transport level before the gateway answers,
something between you and it is speaking HTTP/1.1.
The contract
The contract is one file,fireflo.proto, protobuf package fireflo.v1. It is reproduced in full
on The proto file.
It is frozen from 0.15.9 the way the REST API is frozen: field numbers are never reused or
renumbered, nothing is removed, and additions arrive as new optional fields, new messages and new
methods. A client generated from the 0.15.9 file keeps working against every later gateway; it simply
does not see what was added after it.
Getting the proto
Any of these gives you the same file:-
From the gateway itself. Server reflection is on by default, so a tool that speaks it needs no
file at all:
Your provider may have switched reflection off; then use one of the other two.
- From this site: The proto file, to copy or download.
-
From your provider, as
fireflo.proto.
protoc with the gRPC plugin, buf generate,
python -m grpc_tools.protoc, or the Gradle or Maven protobuf plugin. The file sets go_package
(fireflo/v1;fireflov1) and csharp_namespace (FireFlo.V1); in Java the generated classes are in
package fireflo.v1. It imports only google/protobuf/timestamp.proto, which every protobuf
distribution ships.
Limits that apply to every call
Your provider can change each of these; the figures above are the defaults.
Where to go next
Authentication and sessions
Log in once, carry the token, log in again on SESSION_EXPIRED.
Sending messages
Send and SendStream, every field beside its REST name.
Errors and status codes
REST status, gRPC code, error code, and what to do.
Delivery receipts over gRPC
Subscribe, Pull and Ack — at least once.
Examples
grpcurl, Python, Java and Go.
The proto file
The whole contract.