Referência do SDK do Servidor

Todos os SDKs de servidor do OneSignal são gerados a partir da mesma especificação OpenAPI, portanto compartilham uma interface consistente independentemente da linguagem. Cada SDK envolve a OneSignal REST API e fornece modelos tipados para requisições e respostas.

SDKs disponíveis

Linguagem	Pacote	Repositório
Node.js	@onesignal/node-onesignal	GitHub
Python	onesignal-python-api	GitHub
Java	onesignal-java-client	GitHub
Go	onesignal-go-api	GitHub
PHP	onesignal/onesignal-php-api	GitHub
Ruby	onesignal	GitHub
C# (.NET)	OneSignalApi	GitHub
Rust	onesignal-rust-api	GitHub

Instalação

Os números de versão abaixo são exemplos. Verifique o registro de pacotes de cada SDK para instalar a versão mais recente.

npm install @onesignal/node-onesignal

pip install onesignal-python-api

Maven

<dependency>
  <groupId>com.onesignal</groupId>
  <artifactId>onesignal-java-client</artifactId>
  <version>5.3.0</version>
</dependency>

Gradle

implementation "com.onesignal:onesignal-java-client:5.3.0"

go get github.com/OneSignal/onesignal-go-api/v5

Adicione ao composer.json:

{
  "require": {
    "onesignal/onesignal-php-api": "^5.3"
  }
}

Depois execute composer update.

Adicione ao seu Gemfile:

gem 'onesignal', '~> 5.3'

Depois execute bundle install.

dotnet add package OneSignalApi

Adicione ao Cargo.toml em [dependencies]:

onesignal-rust-api = "5.3.0"

Configuração

Cada SDK requer autenticação via chaves de API. Dois tipos de chave estão disponíveis:

REST API Key — necessária para a maioria dos endpoints (envio de notificações, gerenciamento de usuários, etc.). Encontrada em Configurações > Chaves e IDs do seu app.
Organization API Key — necessária apenas para endpoints no nível da organização, como criar ou listar apps. Encontrada em Configurações da Organização.

const OneSignal = require('@onesignal/node-onesignal');

const configuration = OneSignal.createConfiguration({
  restApiKey: 'YOUR_REST_API_KEY',
  organizationApiKey: 'YOUR_ORGANIZATION_API_KEY',
});

const client = new OneSignal.DefaultApi(configuration);

import onesignal
from onesignal.api import default_api

configuration = onesignal.Configuration(
    rest_api_key='YOUR_REST_API_KEY',
    organization_api_key='YOUR_ORGANIZATION_API_KEY',
)

with onesignal.ApiClient(configuration) as api_client:
    client = default_api.DefaultApi(api_client)

import com.onesignal.client.ApiClient;
import com.onesignal.client.Configuration;
import com.onesignal.client.auth.HttpBearerAuth;
import com.onesignal.client.api.DefaultApi;

ApiClient defaultClient = Configuration.getDefaultApiClient();

HttpBearerAuth restApiAuth = (HttpBearerAuth) defaultClient
    .getAuthentication("rest_api_key");
restApiAuth.setBearerToken("YOUR_REST_API_KEY");

HttpBearerAuth orgApiAuth = (HttpBearerAuth) defaultClient
    .getAuthentication("organization_api_key");
orgApiAuth.setBearerToken("YOUR_ORGANIZATION_API_KEY");

DefaultApi client = new DefaultApi(defaultClient);

import onesignal "github.com/OneSignal/onesignal-go-api"

restAuth := context.WithValue(
    context.Background(),
    onesignal.RestApiKey,
    "YOUR_REST_API_KEY",
)

orgAuth := context.WithValue(
    restAuth,
    onesignal.OrganizationApiKey,
    "YOUR_ORGANIZATION_API_KEY",
)

apiClient := onesignal.NewAPIClient(onesignal.NewConfiguration())

use onesignal\client\api\DefaultApi;
use onesignal\client\Configuration;
use GuzzleHttp;

$config = Configuration::getDefaultConfiguration()
    ->setRestApiKeyToken('YOUR_REST_API_KEY')
    ->setOrganizationApiKeyToken('YOUR_ORGANIZATION_API_KEY');

$client = new DefaultApi(
    new GuzzleHttp\Client(),
    $config
);

require 'onesignal'

OneSignal.configure do |config|
  config.rest_api_key = 'YOUR_REST_API_KEY'
  config.organization_api_key = 'YOUR_ORGANIZATION_API_KEY'
end

client = OneSignal::DefaultApi.new

using OneSignalApi.Api;
using OneSignalApi.Client;

var config = new Configuration();
config.BasePath = "https://api.onesignal.com";
config.AccessToken = "YOUR_REST_API_KEY";

var client = new DefaultApi(config);

use onesignal::apis::configuration::Configuration;

fn create_configuration() -> Configuration {
    let mut config = Configuration::new();
    config.rest_api_key_token = Some("YOUR_REST_API_KEY".to_string());
    config.organization_api_key_token = Some("YOUR_ORGANIZATION_API_KEY".to_string());
    config
}

Armazene suas chaves de API em variáveis de ambiente ou em um gerenciador de segredos. Nunca as commite no controle de versão.

Enviar uma notificação push

Envie notificações push para Assinaturas web e móveis segmentando um segmento. Estes exemplos mostram o caminho feliz — adicione tratamento de erros (try/catch, callbacks de erro) para uso em produção.

const notification = new OneSignal.Notification();
notification.app_id = 'YOUR_APP_ID';
notification.contents = { en: 'Hello from OneSignal!' };
notification.headings = { en: 'Push Notification' };
notification.included_segments = ['Subscribed Users'];

const response = await client.createNotification(notification);
console.log('Notification ID:', response.id);

notification = onesignal.Notification(
    app_id='YOUR_APP_ID',
    contents=onesignal.StringMap(en='Hello from OneSignal!'),
    headings=onesignal.StringMap(en='Push Notification'),
    included_segments=['Subscribed Users'],
)

response = client.create_notification(notification)
print('Notification ID:', response.id)

import com.onesignal.client.model.Notification;
import com.onesignal.client.model.StringMap;

Notification notification = new Notification();
notification.setAppId("YOUR_APP_ID");

StringMap contents = new StringMap();
contents.en("Hello from OneSignal!");
notification.setContents(contents);

StringMap headings = new StringMap();
headings.en("Push Notification");
notification.setHeadings(headings);

notification.setIncludedSegments(Arrays.asList("Subscribed Users"));

var response = client.createNotification(notification);
System.out.println("Notification ID: " + response.getId());

notification := *onesignal.NewNotification("YOUR_APP_ID")
notification.SetContents(onesignal.StringMap{En: onesignal.PtrString("Hello from OneSignal!")})
notification.SetHeadings(onesignal.StringMap{En: onesignal.PtrString("Push Notification")})
notification.SetIncludedSegments([]string{"Subscribed Users"})

response, _, err := apiClient.DefaultApi
    .CreateNotification(orgAuth)
    .Notification(notification)
    .Execute()

if err != nil {
    log.Fatal(err)
}
fmt.Println("Notification ID:", response.GetId())

use onesignal\client\model\Notification;
use onesignal\client\model\StringMap;

$content = new StringMap();
$content->setEn('Hello from OneSignal!');

$headings = new StringMap();
$headings->setEn('Push Notification');

$notification = new Notification();
$notification->setAppId('YOUR_APP_ID');
$notification->setContents($content);
$notification->setHeadings($headings);
$notification->setIncludedSegments(['Subscribed Users']);

$response = $client->createNotification($notification);
echo 'Notification ID: ' . $response->getId();

notification = OneSignal::Notification.new({
  app_id: 'YOUR_APP_ID',
  contents: { en: 'Hello from OneSignal!' },
  headings: { en: 'Push Notification' },
  included_segments: ['Subscribed Users']
})

response = client.create_notification(notification)
puts "Notification ID: #{response.id}"

using OneSignalApi.Model;

var notification = new Notification(appId: "YOUR_APP_ID")
{
    Contents = new StringMap(en: "Hello from OneSignal!"),
    Headings = new StringMap(en: "Push Notification"),
    IncludedSegments = new List<string> { "Subscribed Users" }
};

var response = client.CreateNotification(notification);
Console.WriteLine("Notification ID: " + response.Id);

Nota: O SDK .NET não normaliza automaticamente caracteres de nova linha. Se o seu conteúdo contiver \r\n, normalize antes de passar para Contents:

var normalizedContent = yourContent
   .Replace("\\r\\n", "\n")
   .Replace("\\n", "\n")
   .Replace("\r\n", "\n")
   .Replace("\r", "\n");

use onesignal::apis::default_api;
use onesignal::models::{Notification, StringMap};

let mut contents = StringMap::new();
contents.en = Some("Hello from OneSignal!".to_string());

let mut headings = StringMap::new();
headings.en = Some("Push Notification".to_string());

let mut notification = Notification::new("YOUR_APP_ID".to_string());
notification.contents = Some(Box::new(contents));
notification.headings = Some(Box::new(headings));
notification.included_segments = Some(vec!["Subscribed Users".to_string()]);

let config = create_configuration();
let response = default_api::create_notification(&config, notification).await;

Enviar um email

Envie emails para Assinaturas com o canal email.

const notification = new OneSignal.Notification();
notification.app_id = 'YOUR_APP_ID';
notification.email_subject = 'Important Update';
notification.email_body = '<h1>Hello!</h1><p>This is an HTML email.</p>';
notification.included_segments = ['Subscribed Users'];
notification.channel_for_external_user_ids = 'email';

const response = await client.createNotification(notification);

notification = onesignal.Notification(
    app_id='YOUR_APP_ID',
    email_subject='Important Update',
    email_body='<h1>Hello!</h1><p>This is an HTML email.</p>',
    included_segments=['Subscribed Users'],
    channel_for_external_user_ids='email',
)

response = client.create_notification(notification)

Notification notification = new Notification();
notification.setAppId("YOUR_APP_ID");
notification.setEmailSubject("Important Update");
notification.setEmailBody("<h1>Hello!</h1><p>This is an HTML email.</p>");
notification.setIncludedSegments(Arrays.asList("Subscribed Users"));
notification.setChannelForExternalUserIds("email");

var response = client.createNotification(notification);

notification := *onesignal.NewNotification("YOUR_APP_ID")
notification.SetEmailSubject("Important Update")
notification.SetEmailBody("<h1>Hello!</h1><p>This is an HTML email.</p>")
notification.SetIncludedSegments([]string{"Subscribed Users"})
notification.SetChannelForExternalUserIds("email")

response, _, err := apiClient.DefaultApi
    .CreateNotification(orgAuth)
    .Notification(notification)
    .Execute()

$notification = new Notification();
$notification->setAppId('YOUR_APP_ID');
$notification->setEmailSubject('Important Update');
$notification->setEmailBody('<h1>Hello!</h1><p>This is an HTML email.</p>');
$notification->setIncludedSegments(['Subscribed Users']);
$notification->setChannelForExternalUserIds('email');

$response = $client->createNotification($notification);

notification = OneSignal::Notification.new({
  app_id: 'YOUR_APP_ID',
  email_subject: 'Important Update',
  email_body: '<h1>Hello!</h1><p>This is an HTML email.</p>',
  included_segments: ['Subscribed Users'],
  channel_for_external_user_ids: 'email'
})

response = client.create_notification(notification)

var notification = new Notification(appId: "YOUR_APP_ID")
{
    EmailSubject = "Important Update",
    EmailBody = "<h1>Hello!</h1><p>This is an HTML email.</p>",
    IncludedSegments = new List<string> { "Subscribed Users" },
    ChannelForExternalUserIds = "email"
};

var response = client.CreateNotification(notification);

let mut notification = Notification::new("YOUR_APP_ID".to_string());
notification.email_subject = Some("Important Update".to_string());
notification.email_body = Some("<h1>Hello!</h1><p>This is an HTML email.</p>".to_string());
notification.included_segments = Some(vec!["Subscribed Users".to_string()]);
notification.channel_for_external_user_ids = Some("email".to_string());

let response = default_api::create_notification(&config, notification).await;

Enviar um SMS

Envie mensagens de texto SMS para Assinaturas com o canal sms.

const notification = new OneSignal.Notification();
notification.app_id = 'YOUR_APP_ID';
notification.contents = { en: 'Your SMS message content here' };
notification.included_segments = ['Subscribed Users'];
notification.channel_for_external_user_ids = 'sms';
notification.sms_from = '+15551234567';

const response = await client.createNotification(notification);

notification = onesignal.Notification(
    app_id='YOUR_APP_ID',
    contents=onesignal.StringMap(en='Your SMS message content here'),
    included_segments=['Subscribed Users'],
    channel_for_external_user_ids='sms',
    sms_from='+15551234567',
)

response = client.create_notification(notification)

StringMap contents = new StringMap();
contents.en("Your SMS message content here");

Notification notification = new Notification();
notification.setAppId("YOUR_APP_ID");
notification.setContents(contents);
notification.setIncludedSegments(Arrays.asList("Subscribed Users"));
notification.setChannelForExternalUserIds("sms");
notification.setSmsFrom("+15551234567");

var response = client.createNotification(notification);

notification := *onesignal.NewNotification("YOUR_APP_ID")
notification.SetContents(onesignal.StringMap{En: onesignal.PtrString("Your SMS message content here")})
notification.SetIncludedSegments([]string{"Subscribed Users"})
notification.SetChannelForExternalUserIds("sms")
notification.SetSmsFrom("+15551234567")

response, _, err := apiClient.DefaultApi
    .CreateNotification(orgAuth)
    .Notification(notification)
    .Execute()

$content = new StringMap();
$content->setEn('Your SMS message content here');

$notification = new Notification();
$notification->setAppId('YOUR_APP_ID');
$notification->setContents($content);
$notification->setIncludedSegments(['Subscribed Users']);
$notification->setChannelForExternalUserIds('sms');
$notification->setSmsFrom('+15551234567');

$response = $client->createNotification($notification);

notification = OneSignal::Notification.new({
  app_id: 'YOUR_APP_ID',
  contents: { en: 'Your SMS message content here' },
  included_segments: ['Subscribed Users'],
  channel_for_external_user_ids: 'sms',
  sms_from: '+15551234567'
})

response = client.create_notification(notification)

var notification = new Notification(appId: "YOUR_APP_ID")
{
    Contents = new StringMap(en: "Your SMS message content here"),
    IncludedSegments = new List<string> { "Subscribed Users" },
    ChannelForExternalUserIds = "sms",
    SmsFrom = "+15551234567"
};

var response = client.CreateNotification(notification);

let mut contents = StringMap::new();
contents.en = Some("Your SMS message content here".to_string());

let mut notification = Notification::new("YOUR_APP_ID".to_string());
notification.contents = Some(Box::new(contents));
notification.included_segments = Some(vec!["Subscribed Users".to_string()]);
notification.channel_for_external_user_ids = Some("sms".to_string());
notification.sms_from = Some("+15551234567".to_string());

let response = default_api::create_notification(&config, notification).await;

Referência completa da API

Cada SDK de servidor suporta o mesmo conjunto de endpoints da API. Consulte a documentação da API do seu SDK para a lista completa de métodos, incluindo usuários, assinaturas, segmentos, templates e mais.

SDK	Referência da API
Node.js	DefaultApi.md
Python	DefaultApi.md
Java	DefaultApi.md
Go	DefaultApi.md
PHP	DefaultApi.md
Ruby	DefaultApi.md
C# (.NET)	DefaultApi.md
Rust	default_api docs

Para a REST API subjacente, consulte a referência completa da API.

FAQ

Qual SDK de servidor devo escolher?

Use o SDK que corresponde à sua linguagem de backend. Todos os SDKs de servidor são gerados a partir da mesma especificação OpenAPI e suportam os mesmos endpoints, portanto a funcionalidade é idêntica entre as linguagens.

Qual é a diferença entre a REST API Key e a Organization API Key?

A REST API Key tem escopo para um único app e é necessária para a maioria das operações, como enviar notificações e gerenciar usuários. A Organization API Key tem escopo para sua organização e só é necessária para criar ou listar apps. A maioria das integrações só precisa da REST API Key.

Posso usar a REST API diretamente em vez de um SDK?

Sim. Os SDKs de servidor são invólucros convenientes em torno da OneSignal REST API. Você pode chamar a API diretamente usando qualquer cliente HTTP com o esquema de autenticação key (Authorization: key YOUR_REST_API_KEY).

Esses SDKs são gerados automaticamente?

Sim. Todos os SDKs de servidor são gerados a partir da especificação OpenAPI do OneSignal usando o OpenAPI Generator. Isso garante cobertura de API consistente em todas as linguagens.

Páginas relacionadas

Visão geral da API REST

Endpoints, autenticação, limites de taxa e formatos de requisição/resposta.

Chaves e IDs

Encontre seu App ID, chave de API REST e chave de API da Organização.

Mensagens transacionais

Envie OTPs, recibos e alertas urgentes via API com dados personalizados.

Verificação de identidade

Proteja sua integração com JWTs gerados pelo servidor para evitar a personificação de Usuários.

Using the REST APIs

API reference

SDKs

Referência do SDK do Servidor

SDKs disponíveis

Instalação

Configuração

Enviar uma notificação push

Enviar um email

Enviar um SMS

Referência completa da API

FAQ

Qual SDK de servidor devo escolher?

Qual é a diferença entre a REST API Key e a Organization API Key?

Posso usar a REST API diretamente em vez de um SDK?

Esses SDKs são gerados automaticamente?

Páginas relacionadas

Visão geral da API REST

Chaves e IDs

Mensagens transacionais

Verificação de identidade

​SDKs disponíveis

​Instalação

​Configuração

​Enviar uma notificação push

​Enviar um email

​Enviar um SMS

​Referência completa da API

​FAQ

​Qual SDK de servidor devo escolher?

​Qual é a diferença entre a REST API Key e a Organization API Key?

​Posso usar a REST API diretamente em vez de um SDK?

​Esses SDKs são gerados automaticamente?

​Páginas relacionadas

Visão geral da API REST

Chaves e IDs

Mensagens transacionais

Verificação de identidade

SDKs disponíveis

Instalação

Configuração

Enviar uma notificação push

Enviar um email

Enviar um SMS

Referência completa da API

FAQ

Qual SDK de servidor devo escolher?

Qual é a diferença entre a REST API Key e a Organization API Key?

Posso usar a REST API diretamente em vez de um SDK?

Esses SDKs são gerados automaticamente?

Páginas relacionadas