💬 SMS

Overview

SMS notifications provide instant, direct communication with your users. Pingram makes it easy to send personalized SMS messages with features like proper phone number formatting, delivery tracking, and global reach.

This guide covers everything you need to know about sending SMS notifications, from basic setup to advanced features.

Requirements

• No setup required

Step 1: Create your account and first notification

• Create your Pingram account and complete the onboarding. Sign up for free.
• In the dashboard, create your first notification and enable the SMS channel.
• Note the notification’s Type (e.g., welcome_sms). You’ll use this later in the send step.

Step 2: Install the SDK

In the dashboard send step, the first thing you’ll need to do is install the SDK. Select the appropriate language and follow the instructions.

npm install pingram

yarn add pingram

pnpm add pingram

pip install pingram-python

composer require pingram/php

go get github.com/pingram-io/pingram-go

dotnet add package Pingram

<dependencies>
    <dependency>
        <groupId>io.pingram</groupId>
        <artifactId>pingram</artifactId>
        <version>0.1.0</version>
    </dependency>
</dependencies>

gem install pingram

Step 3: Send an SMS Notification

The next part of the send step is to send the notification from your backend. Here’s how to send an SMS notification by passing the SMS content directly:

import { Pingram } from 'pingram';

// Initialize (default US region)
// For CA region: add region: 'ca' on new line after apiKey
// For EU region: add region: 'eu' on new line after apiKey
const pingram = new Pingram({
  apiKey: 'Your api key here'
});

// Send SMS notification (direct content)
pingram.send({
  type: 'welcome_sms',
  to: {
    id: 'user123',
    number: '+16175551212' // Replace using format [+][country code][area code][local number]
  },
  sms: {
    message: 'Welcome to Acme Corp! Thanks for joining.'
  }
});

import asyncio
from pingram import Pingram

async def send_sms():
    async with Pingram(api_key="pingram_sk_...") as client:
        await client.send({
            "type": "welcome_sms",
            "to": {
                "id": "user123",
                "number": "+16175551212"  # Replace using format [+][country code][area code][local number]
            },
            "sms": {
                "message": "Welcome to Acme Corp! Thanks for joining."
            }
        })

# Run the async function
asyncio.run(send_sms())

use Pingram\Client;
use Pingram\Model\SenderPostBody;

$client = new Client('pingram_sk_...');

$body = new SenderPostBody([
    'type' => 'welcome_sms',
    'to' => [
        'id' => 'user123',
        'number' => '+16175551212'  // Replace using format [+][country code][area code][local number]
    ],
    'sms' => [
        'message' => 'Welcome to Acme Corp! Thanks for joining.'
    ]
]);
$client->send($body);

package main

import (
    "context"
    "log"

    pingram "github.com/pingram-io/pingram-go"
)

func main() {
    client := pingram.NewClient("pingram_sk_...") // Your secret API key

    body := pingram.SenderPostBody{
        Type: pingram.PtrString("welcome_sms"),
        User: &pingram.GetUsersResponseUsersInner{
            Id:     "user123",
            Number: pingram.PtrString("+16175551212"), // Replace using format [+][country code][area code][local number]
        },
        Sms: &pingram.SenderPostBodySms{
            Message: pingram.PtrString("Welcome to Acme Corp! Thanks for joining."),
        },
    }

    _, _, err := client.DefaultAPI.Send(context.Background()).SenderPostBody(body).Execute()
    if err != nil {
        log.Fatal(err)
    }
}

using Pingram;
using Pingram.Model;

var client = new PingramClient("your_api_key");
var body = new SenderPostBody
{
    Type = "welcome_sms",
    To = new SenderPostBodyTo { Id = "user123", Number = "+16175551212" }, // Replace using format [+][country code][area code][local number]
    Sms = new SenderPostBodySms { Message = "Welcome to Acme Corp! Thanks for joining." }
};
await client.SendAsync(body);

package com.example;

import io.pingram.Pingram;
import io.pingram.model.*;

public class Example {
    public static void main(String[] args) {
        Pingram pingram = new Pingram("pingram_sk_..."); // Your secret API key

        SenderPostBodyTo to = new SenderPostBodyTo()
            .id("user123")
            .number("+16175551212"); // Replace using format [+][country code][area code][local number]

        SenderPostBody body = new SenderPostBody()
            .type("welcome_sms")
            .to(to)
            .sms(new SenderPostBodySms()
                .message("Welcome to Acme Corp! Thanks for joining.")
            );

        SenderPostResponse response = pingram.send(body);
        System.out.println("Tracking ID: " + response.getTrackingId());
    }
}

require 'pingram'

client = Pingram::Client.new(api_key: 'pingram_sk_...')
body = Pingram::SenderPostBody.new(
  type: 'welcome_sms',
  to: { id: 'user123', number: '+16175551212' },
  sms: { message: 'Welcome to Acme Corp! Thanks for joining.' }
)
client.send(body)

You’re All Set!

🎉 Congrats! You’re now sending notifications!

If you’d like to send using templates configured in the Dashboard, check out our Templating guide and Backend Integration, or learn more about SMS best practices below.

Phone Number Formatting

Proper phone number formatting is crucial for SMS delivery. Always use the international E.164 format with a plus sign and country code.

E.164 Format (Required)

Use the E.164 format for all phone numbers:

// ✅ Correct E.164 format examples
pingram.send({
  type: 'order_update',
  to: {
    id: 'user456',
    number: '+16175551212' // US number
  },
  parameters: {
    orderNumber: 'ORD-123',
    status: 'shipped'
  }
});

// More E.164 examples
const phoneNumbers = [
  '+16175551212', // United States
  '+447911123456', // United Kingdom
  '+33123456789', // France
  '+81901234567', // Japan
  '+5511987654321', // Brazil
  '+4917612345678', // Germany
  '+61412345678' // Australia
];

When sending notifications, format the phone numbers with a + and country code, for example, +16175551212 (E.164 standard). We accept unformatted US/Canada numbers, e.g., (415) 555-1212, 415-555-1212, or 4155551212.

Sender Phone Numbers

Free Accounts:

• +16505093842
• For countries where a “name” shows instead of a phone number, the default sender ID is NOTIAPI.

Paid Accounts:

• Dedicated phone number
• By default, from the +1 (650) area code but can be changed to other area codes, short codes, or toll-free numbers
• For countries where a “name” shows instead of a phone number, we can modify the sender ID.

See more sender options and details here: Sender phone numbers.

SMS Best Practices

1. Message Length and Content

Character Limits:

• SMS limit: 800 ASCII characters maximum
• Recommended: Keep messages under 160 characters for single SMS segments
• Long messages: Automatically split into multiple segments
• Avoid spam: Don’t send excessive messages

2. Compliance and Consent

• Opt-in required: Ensure users have consented to SMS notifications
• Opt-out mechanism: Include unsubscribe instructions when required
• Regulatory compliance: Follow local regulations (TCPA in US, GDPR in EU)
• Record keeping: Maintain consent records
• Avoid spam: Don’t send excessive messages

A2P 10DLC Registration (US)

See the dedicated guide: A2P 10DLC Registration

SMS Responses and Two-Way Communication

Pingram supports receiving and processing SMS replies via webhooks. When recipients reply to your SMS notifications, we automatically forward these responses to your configured webhook endpoint.

SMS Inbound Webhook

When a user replies to your SMS within 7 days of your last outbound message:

1. Pingram receives the inbound SMS from the carrier
2. The reply is matched to the original conversation
3. Pingram forwards the reply to your webhook endpoint
4. All replies are visible in your Logs dashboard

Setup: Enable the SMS_INBOUND event in Webhook page. See our Inbound Messages documentation for full details and webhook payload format.

SMS Auto-Reply

Automatically respond to inbound SMS messages without manual intervention. This is useful for scenarios like:

• “We don’t monitor replies to this number. For support, email support@company.com”
• “Thanks for your message. Our team will respond shortly.”

Configure auto-reply in your send request:

pingram.send({
  type: 'appointment_reminder',
  to: {
    id: 'user123',
    number: '+15005550006'
  },
  sms: {
    message: 'Your appointment is tomorrow at 2pm.',
    autoReply: {
      message: 'Thanks for your response! We look forward to seeing you.'
    }
  }
});

Auto-Reply Behavior:

• Sent once per recipient phone number per account (no spam)
• Opt-out keywords (STOP, CANCEL, etc.) skip auto-reply
• Fully logged in your Logs dashboard

See our Inbound Messages documentation for full details.

Your Own Telecom Team

Imagine having your own “Telecom” team:

• Regulatory Compliance: More and more countries and telecom companies are joining forces to prevent SMS spam. We help our customers navigate these regulations and stay compliant, by registering your numbers, submitting necessary documentations, verifying your business in different juristictions, applying for elevated access, and more.

• Delivery Monitoring: We also monitor your SMS delivery rates and will reach out to you directly if we detect an alarming rate of failure. You can also rely on our team for best practices, reviewing your SMS content, or to help you troubleshoot a delivery issue.

• Transferring existing numbers: We can also navigate the transfer of any existing numbers to our care, so your team can focus on your software and core product.

Tracking and Analytics

Pingram automatically tracks SMS metrics:

• Delivery status: Successfully delivered messages
• Failed deliveries: Numbers that couldn’t receive messages

View all analytics in your dashboard under Logs and Insights.

Events Webhook

Following are the events that you can receive via Events Webhook:

• Delivery confirmations
• Failures
• Unsubscribes
• Inbound replies (SMS_INBOUND)

Need more help?

If you need help, reach out through our live chat or Slack community.