# Enfonica Documentation > How each Enfonica product works, and the reference for the Enfonica API. Enfonica is an Australian cloud telco: Phone Numbers, Cloud SMS, Cloud Voice, Cloud SIP, and Flow, each managed in a project in the Enfonica Console. Answers to problems and how-to questions are in the Enfonica Help Center: https://enfonica.com/help/llms.txt ## Before you build - [Overview](https://enfonica.com/docs/): What you can build on Enfonica, how the platform fits together, what's supported, and the limits to plan for. Read this first when deciding whether Enfonica suits an app. - Not supported: MMS (Cloud SMS sends and receives text only), WebRTC (there's no SDK for calling from a browser or a mobile app), and a phone system or PBX (Cloud SIP provides SIP trunks that connect one). Don't design an app around these. - An Enfonica account is opened by the Enfonica team at https://enfonica.com/sales?segment=saas-developer. There's no self-service sign-up. A request succeeds only when the user has an account, a project, and a service account key, so ask the user for these instead of trying to create them. - [Limits](https://enfonica.com/docs/platform/limits/): Every limit that the API, webhooks, messages, calls, and phone numbers have. The ones that most often change a design: - An SMS is at most 10 segments: 1,530 characters in the GSM-7 alphabet, or 670 if any character is outside it, such as an emoji. A longer `body` is cut to fit, without an error. - Each request to send an SMS has one `to` number. - Your server has 10 seconds to answer a webhook or a VoiceML request. SMS and event webhooks are retried for more than three hours. A VoiceML request isn't retried: if no handler URL answers, the call fails. - A call lasts at most 4 hours. - List methods return 10 items by default and 100 at most. A larger `pageSize` returns `INVALID_ARGUMENT`. ## Calling the Enfonica API - Use the REST API, and authenticate with a service account key. A service account belongs to one project, or to an organisation (it then works in every project in the organisation, and its key file's `project_id` is `-`). Its JSON key file is created in the Enfonica Console. - To authenticate, download the code sample for your language and add it to the project as it is. Don't rewrite it from memory or from the page. Each sample is one tested file that exchanges the key for an access token, caches it, and returns the `Authorization: Bearer ` header value. It reads the key file path from the `ENFONICA_APPLICATION_CREDENTIALS` environment variable. - Python: https://enfonica.com/docs/samples/oauth/python/enfonica_credentials.py (needs the `cryptography` package) - Node.js (TypeScript): https://enfonica.com/docs/samples/oauth/nodejs/enfonica-credentials.ts (Node.js 18 or later, no packages) - Go: https://enfonica.com/docs/samples/oauth/go/enfonica_credentials.go (standard library only) - C# (.NET): https://enfonica.com/docs/samples/oauth/dotnet/EnfonicaCredentials.cs (no packages) - Java: https://enfonica.com/docs/samples/oauth/java/EnfonicaCredentials.java (needs `jackson-databind`) - PHP: https://enfonica.com/docs/samples/oauth/php/EnfonicaCredentials.php (needs the `openssl` and `curl` extensions) - Ruby: https://enfonica.com/docs/samples/oauth/ruby/enfonica_credentials.rb (needs the `jwt` gem) - In another language, implement the token exchange that the Authentication page describes (OAuth 2.0 JWT bearer grant, RFC 7523). Send the access token from the exchange, never the self-signed JWT. - Create one credentials instance for the life of the app, and reuse it for every request. A `401` or `403` from the API means the key, project, or role is wrong. Don't retry it with a new token. - The REST API follows Google Cloud API conventions (https://cloud.google.com/apis/design). It's a JSON transcoding of the gRPC API, so the gRPC `.proto` definitions and the REST API have the same resources and fields. - Each product has its own host, which serves both REST and gRPC on port 443: `numbering.api.enfonica.com` (Phone Numbers, `v1beta1`), `messaging.api.enfonica.com` (Cloud SMS, `v1`), and `voice.api.enfonica.com` (Cloud Voice, `v1beta1`). - Resources have names like `projects/my-project/phoneNumberInstances/123`, and are accessed through the standard methods: `List` (`GET /v1beta1/{parent}/phoneNumberInstances`), `Get` (`GET /v1beta1/{name}`), `Create` (`POST`), `Update` (`PATCH` with an `updateMask`), and `Delete`. Custom methods use a colon, such as `POST /v1beta1/{name}:move`. - JSON field names are lowerCamelCase, such as `phoneNumber` and `createTime`. Enums are strings. Timestamps are RFC 3339 strings. - List methods take `pageSize` and `pageToken`, and return `nextPageToken` until the last page. - Errors return an HTTP status with a JSON body of `code`, `message`, and `details`, as in `google.rpc.Status`. ## Sending a first SMS The REST API and the Node.js client library send the same message, with the same fields. Use the REST API unless the project already uses an Enfonica client library or the user asks for one. - REST API, in any language: `POST https://messaging.api.enfonica.com/v1/projects/my-project/messages`, with the `Authorization` header from the code sample above. The project is in the path, and the JSON body is the message: ```json { "to": "+61491570156", "from": "+61491570110", "body": "Hello from Enfonica" } ``` To receive replies and the delivery status at your server, add `replyUrl` and `statusUpdateUrl` to the message. To send a message that isn't checked against the project's unsubscribers, such as a code or a reminder, add `"classification": "TRANSACTIONAL"`. Without it, a message to someone who has replied STOP is refused with `FAILED_PRECONDITION`. The API sends a message as soon as you create it. To send one later, schedule the request in your app. Creating a message isn't idempotent: the same request sent twice sends two messages, so don't retry a request unless you know that it failed. - Node.js client library: `npm install @enfonica/messaging` (Node.js 10 or later). It reads the key file from `ENFONICA_APPLICATION_CREDENTIALS` and gets access tokens itself, so it doesn't need the code sample above. The project goes in `parent`, and the REST body goes in `message`: ```js // In an ES module or TypeScript: import * as messaging from '@enfonica/messaging'; const messaging = require('@enfonica/messaging'); const client = new messaging.MessagesClient(); // create once, and reuse it async function sendMessage() { const [message] = await client.createMessage({ parent: 'projects/my-project', message: { to: '+61491570156', from: '+61491570110', body: 'Hello from Enfonica' }, }); return message; } ``` - `to` is a phone number in E.164 format. `from` is an SMS-enabled phone number in the project, or an alphanumeric sender ID of up to 11 characters. A message to an Australian number from a sender ID that isn't registered is refused. - The response is the message. Its `name`, such as `projects/my-project/messages/j6tfskeu3q0t6k3hp4fnh7d19c1p1p`, identifies it. To check its `status`, get it again with `GET /v1/{name}`, or `client.getMessage({ name })`. - [Client libraries](https://enfonica.com/docs/libraries/overview/): Enfonica publishes client libraries for Node.js and .NET. The Node.js packages are `@enfonica/messaging` (Cloud SMS), `@enfonica/voice` (Cloud Voice), and `@enfonica/numbering` (Phone Numbers). - [Node.js client library usage](https://enfonica.com/docs/libraries/nodejs/usage/): Import the library, reuse one client, call methods with `await`, and page through lists. - [Getting started with Node.js](https://enfonica.com/docs/libraries/nodejs/getting-started/): A tutorial that sends an SMS and replies to incoming SMS from a webhook. ## Receiving webhooks Enfonica sends a webhook as an HTTP POST with a JSON body, an `X-Enfonica-Event` header that names the event, and an `X-Enfonica-Signature` header. - Check the signature before trusting the request: `Base64(HMAC-SHA256(key, url + event + body))`. [Request signing](https://enfonica.com/docs/platform/request-signing/) has the algorithm, reference code, and a test vector. - `key` is the project's signing key. The Enfonica Console shows it as base64, so decode it to its 64 bytes first. - `url` is the full URL that Enfonica requested, with its query string. Use the URL as you gave it to Enfonica. Don't rebuild it from the `Host` header behind a proxy. - `event` is the value of the `X-Enfonica-Event` header, such as `INCOMING_MESSAGE` or `MESSAGE_STATUS_UPDATE`. - `body` is the raw request body. Read the raw bytes before any JSON parser runs, and don't serialize the JSON again. - Respond with a 2xx status within 10 seconds. A failed webhook is retried, and a slow response is too, so the same webhook can arrive more than once. - For an incoming SMS (`INCOMING_MESSAGE`), reply by returning [MessageML](https://enfonica.com/docs/cloud-sms/messageml/) with `Content-Type: text/xml`, or return `204 No Content` to send nothing. - After you send a message with `replyUrl`, every SMS that the person sends to that number goes to that URL, not only a direct reply. - A reply of STOP adds the sender to the project's unsubscribers, and still arrives as an incoming message. - A MessageML `` reply is checked against the project's unsubscribers, so it isn't sent to someone who has replied STOP. - A VoiceML request, which asks what to do with a live call, isn't retried. If no handler URL returns VoiceML within 10 seconds, the call fails. ## Platform - [Authentication](https://enfonica.com/docs/authentication/): How API authentication works, the service account key code samples, and the token exchange step by step. - [Service accounts](https://enfonica.com/docs/projects/service-accounts/): Create a project's or an organisation's service account and download its JSON key file. - [Projects](https://enfonica.com/docs/projects/overview/): Projects hold your Enfonica resources, and appear in every API resource name. - [Access control](https://enfonica.com/docs/projects/access-control/): Roles and permissions for users and service accounts. - [Create projects with the API](https://enfonica.com/docs/projects/create-projects-api/): Create a project for each of your customers and link it to your billing account, with an organisation's service account. - [Request signing](https://enfonica.com/docs/platform/request-signing/): Verify that a webhook request came from Enfonica, from its `X-Enfonica-Signature` header. - [Toll fraud prevention](https://enfonica.com/docs/platform/toll-fraud-prevention/): How Enfonica detects international toll fraud, and how to configure it for your project. - [Limits](https://enfonica.com/docs/platform/limits/): The limits on the API, webhooks, SMS, calls, and phone numbers. - [Usage data over SFTP](https://enfonica.com/docs/platform/usage-data/sftp/), [Call records](https://enfonica.com/docs/platform/usage-data/call-records/), [SMS records](https://enfonica.com/docs/platform/usage-data/sms-records/): Download call and SMS records in bulk. ## Phone Numbers - [Overview](https://enfonica.com/docs/phone-numbers/overview/): Search for, buy, and manage phone numbers. - [Regulatory guidelines](https://enfonica.com/docs/phone-numbers/regulatory-guidelines/overview/): Registration requirements for each type of phone number. - [REST API reference](https://enfonica.com/docs/phone-numbers/api-reference/rest/overview/): `numbering.api.enfonica.com`, version `v1beta1`. ## Cloud SMS - [Overview](https://enfonica.com/docs/cloud-sms/overview/): Send and receive SMS, with examples of sending and retrieving a message with the REST API, Node.js, and .NET. - [Webhooks](https://enfonica.com/docs/cloud-sms/webhooks/): The requests Enfonica sends to your app when a message arrives or changes status. - [MessageML](https://enfonica.com/docs/cloud-sms/messageml/): Reply to an incoming message from your webhook. - [Alphanumeric sender IDs](https://enfonica.com/docs/cloud-sms/alphanumeric-sender-id/): Send SMS from a business name instead of a number. - [Australian SMS Sender ID Register](https://enfonica.com/docs/cloud-sms/australian-sender-id-register/): Registering sender IDs for Australia. - [REST API reference](https://enfonica.com/docs/cloud-sms/api-reference/rest/overview/): `messaging.api.enfonica.com`, version `v1`. ## Cloud Voice - [Overview](https://enfonica.com/docs/cloud-voice/overview/): Control and monitor incoming and outgoing calls from your app. - [Webhooks](https://enfonica.com/docs/cloud-voice/webhooks/): The requests Enfonica sends to your app during a call. - [VoiceML](https://enfonica.com/docs/cloud-voice/voiceml/overview/): The XML your webhook returns to control a call. - [``](https://enfonica.com/docs/cloud-voice/voiceml/stream/): A call's audio in real time, in both directions. Your app opens a gRPC stream (`Streams.StreamCall`, which has no REST form and isn't a WebSocket), and the `` action connects the call to it. The audio is G.711 mu-law or A-law at 8 kHz. - [Billing](https://enfonica.com/docs/cloud-voice/billing/): How calls are charged. - [REST API reference](https://enfonica.com/docs/cloud-voice/api-reference/rest/overview/): `voice.api.enfonica.com`, version `v1beta1`. ## Cloud SIP - [Overview](https://enfonica.com/docs/cloud-sip/overview/): Connect a phone system (PBX) to Enfonica over SIP. - [Making outgoing calls](https://enfonica.com/docs/cloud-sip/making-calls/), [Load balancing](https://enfonica.com/docs/cloud-sip/load-balancers/), [SIP URIs](https://enfonica.com/docs/cloud-sip/sip-uris/): Route calls to and from your phone system. - [IP addresses](https://enfonica.com/docs/cloud-sip/ip-addresses/), [Firewall configuration](https://enfonica.com/docs/cloud-sip/firewall-configuration/), [Codecs](https://enfonica.com/docs/cloud-sip/codecs/), [Secure media](https://enfonica.com/docs/cloud-sip/secure-media/), [Limits](https://enfonica.com/docs/cloud-sip/limits/): Network and media settings. - [Teams Direct Routing](https://enfonica.com/docs/cloud-sip/guides/teams-direct-routing/): Connect Microsoft Teams to Enfonica. ## Flow - [Overview](https://enfonica.com/docs/flow/): Build call flows for incoming calls in a visual editor in the Console, without code. - [Steps](https://enfonica.com/docs/flow/steps/): Each step that a flow can use. - [Media Library](https://enfonica.com/docs/flow/media-library/), [FAQ](https://enfonica.com/docs/flow/faq/) ## Optional - [SMS Marketing](https://enfonica.com/docs/sms-marketing/overview/): Send SMS campaigns to contact lists from the Console.