Compartir a través de

Biblioteca cliente de códigos cortos de Azure Communication para JavaScript: versión 1.0.0-beta.4

La biblioteca de números de teléfono proporciona funcionalidades para la administración de códigos cortos.

Introducción

Requisitos previos

Instalación de

npm install @azure-tools/communication-short-codes

Compatibilidad con exploradores

Paquete de JavaScript

Para usar esta biblioteca cliente en el explorador, primero debe usar un agrupador. Para más información sobre cómo hacerlo, consulte nuestra documentación de agrupación.

Conceptos clave

El paquete de códigos cortos expone el ShortCodesClient que proporciona métodos para administrar códigos cortos.

Tipos de código corto

Los códigos cortos vienen en dos tipos; shortCode y alphaId. ShortCode = número de 5 dígitos | alphaId = combinación alfanumérica de 5 dígitos.

Códigos cortos

Los códigos cortos son un tipo de número que están disponibles para los clientes empresariales. Vienen en forma de un número de 5 o 6 dígitos y se pueden usar para enviar sms similares a cómo se usa un número geográfico o gratuito. Para adquirir un código corto, es necesario enviar una solicitud o un breve programa.

Breves del programa

Un breve programa realiza un seguimiento de la aplicación para un código corto y contiene toda la información necesaria para procesar la aplicación, así como información sobre el estado de la aplicación y las actualizaciones que pueden ser necesarias. Puede tardar entre 8 y 12 semanas en aprobarse un breve programa y un breve código que se va a emitir una vez enviado el breve programa.

Ejemplos

Authentication

Para crear un objeto de cliente para acceder a la API de Communication Services, necesitará o connection string el endpoint de su recurso de Communication Services y .credential El cliente de números de teléfono puede usar credenciales de Azure Active Directory o una credencial de clave de API para autenticarse.

Puede obtener una clave o una cadena de conexión del recurso de Communication Services en Azure Portal. También puede encontrar el punto de conexión del recurso de Communication Services en Azure Portal.

Una vez que tenga una clave, puede autenticarse ShortCodesClient con cualquiera de los métodos siguientes:

Uso de una cadena de conexión

import { ShortCodesClient } from "@azure-tools/communication-short-codes";

const connectionString = "endpoint=<endpoint>;accessKey=<accessKey>";
const client = new ShortCodesClient(connectionString);

Uso de una clave de acceso con AzureKeyCredential

Si usa una clave para inicializar el cliente, también deberá proporcionar el punto de conexión adecuado. Puede obtener este punto de conexión del recurso de Communication Services en Azure Portal. Una vez que tenga una clave y un punto de conexión, puede autenticarse con el código siguiente:

import { AzureKeyCredential } from "@azure/core-auth";
import { ShortCodesClient } from "@azure-tools/communication-short-codes";

const credential = new AzureKeyCredential("<key-from-resource>");
const client = new ShortCodesClient("<endpoint-from-resource>", credential);

Uso de una credencial de Azure Active Directory

La autenticación de cadena de conexión se usa en la mayoría de los ejemplos, pero también puede autenticarse con Azure Active Directory mediante la biblioteca de identidades de Azure. Para usar el proveedor DefaultAzureCredential que se muestra a continuación u otros proveedores de credenciales proporcionados con el SDK de Azure, instale el @azure/identity paquete:

npm install @azure/identity

El @azure/identity paquete proporciona una variedad de tipos de credenciales que la aplicación puede usar para hacerlo. El archivo LÉAME para @azure/identity proporciona más detalles y ejemplos para empezar.

import { DefaultAzureCredential } from "@azure/identity";
import { ShortCodesClient } from "@azure-tools/communication-short-codes";

let credential = new DefaultAzureCredential();
const client = new ShortCodesClient("<endpoint-from-resource>", credential);

Uso

En las secciones siguientes se proporcionan fragmentos de código que cubren algunas de las tareas comunes mediante el cliente de números de teléfono Azure Communication Services. Los escenarios que se tratan aquí constan de:

Creación y envío de un breve programa

Inicialice un ShortCodesCreateUSProgramBriefParams objeto y rellénelo con los detalles del programa breve.

import { ShortCodesClient } from "@azure-tools/communication-short-codes";

const connectionString = "endpoint=<endpoint>;accessKey=<accessKey>";
const client = new ShortCodesClient(connectionString);

async main function() {
  const programBriefId = "00000000-0000-0000-0000-000000000000";
  const programBriefRequest: ShortCodesCreateUSProgramBriefParams = {
    body: {
      id: programBriefId,
      programDetails: {
        description: "Customers can sign up to receive regular updates on coupons and other perks of our loyalty program.",
        expectedDateOfService: new Date(2022, 1, 25),
        isPoliticalCampaign: false,
        isVanity: false,
        name: "Contoso Loyalty Program",
        numberType: "shortCode",
        privacyPolicyUrl: "https://contoso.com/privacy",
        signUp: "This program will allow customers to receive exclusive offers and information to help them utilize our loyalty program to their best advantage. Customers who opt-in will receive regular coupons they can use in our stores, as well as advanced notice of sales and other promotional and marketing campaigns.",
        signUpTypes: [ "sms", "website" ],
        termsOfServiceUrl: "https://contoso.com/terms",
        url: "https://contoso.com/loyalty-program"
      },
      companyInformation: {
        address: "1 Contoso Way Redmond, WA 98052",
        name: "Contoso",
        url: "contoso.com",
        contactInformation: {
          email: "alex@contoso.com",
          name: "Alex",
          phone: "+14255551234"
        },
        customerCareInformation: {
          email: "customercare@contoso.com",
          tollFreeNumber: "+18005551234"
        }
      },
      messageDetails: {
        types: [ "sms" ],
        recurrence: "subscription",
        contentTypes: [ "coupons", "loyaltyProgram", "loyaltyProgramPointsPrizes" ],
        optInMessage: "Someone requested to subscribe this number to receive updates about Contoso's loyalty program.  To confirm subscription, reply to this message with 'JOIN'",
        optInReply: "JOIN",
        confirmationMessage: "Congrats, you have been successfully subscribed to loyalty program updates.  Welcome!",
        useCase: "two-way"
      },
      trafficDetails: {
        estimatedVolume: 10000,
        monthlyAverageMessagesFromUser: 1,
        monthlyAverageMessagesToUser: 3,
        isSpiky: true,
        spikeDetails: "Higher traffic expected around major shopping holidays, most notably Black Friday and Memorial Day."
      }
    }
  }
}

main();

A continuación, agregue una llamada a upsertUSProgramBrief y use el objeto que creó como parámetro. Esto creará un breve objeto de programa que, a continuación, se puede modificar tanto como sea necesario hasta que esté listo para enviarse.

  // create program brief
  var createResponse = await client.upsertUSProgramBrief(programBriefId, programBriefRequest);
  if (createResponse._response.status != 201) {
    throw new Error(`Program brief creation failed.
    Status code: ${createResponse._response.status}; Error: ${createResponse._response.bodyAsText}; CV: ${createResponse._response.headers.get("MS-CV")}`);
  } else {
    console.log(`Successfully created a new program brief with Id ${programBriefId}.`);
  }

Cuando esté listo para enviarse, llame submitUSProgramBrief a para su procesamiento. Después del envío no se permitirán modificaciones a menos que se solicite como parte del proceso de solicitud.

  // submit program brief
  var submittedProgramBrief = await client.submitUSProgramBrief(programBriefId);
  if (submittedProgramBrief._response.status == 200) {
    console.log(`Successfully submitted program brief with Id ${programBriefId}`);
  } else {
    throw new Error(`Failed to submit program brief with Id ${programBriefId}.
    Status code: ${submittedProgramBrief._response.status}; Error: ${submittedProgramBrief._response.bodyAsText}; CV: ${submittedProgramBrief._response.headers.get("MS-CV")}`);
  }

Obtener y eliminar breves del programa

Use el listUSProgramBriefs método para paginar todos los breves programas de un recurso de ACS. Use deleteUSProgramBrief para eliminar breves programas no deseados. Tenga en cuenta que una vez que se envía un breve programa, no es apto para su eliminación.

import { ShortCodesClient } from "@azure-tools/communication-short-codes";

const connectionString = "endpoint=<endpoint>;accessKey=<accessKey>";
const client = new ShortCodesClient(connectionString);

async main function() {
  // get all program briefs for a resource
  var programBriefs = await client.listUSProgramBriefs();

  // find draft program briefs, and delete them
  for await (const programBrief of programBriefs) {
    console.log(`Program Brief with Id ${programBrief.id} has status ${programBrief.status}`);

    // identify drafts
    if (programBrief.status == 'draft') {
      var unsubmittedProgramBriefId = programBrief.id;
    
      // delete draft program brief
      var deleteResponse = await client.deleteUSProgramBrief(unsubmittedProgramBriefId);
      if (deleteResponse._response.status == 200) {
          console.log(`Successfully deleted draft program brief with Id ${unsubmittedProgramBriefId}`);
      } else {
          console.log(`Failed to delete draft program brief with Id ${unsubmittedProgramBriefId}.
          Status code: ${deleteResponse._response.status}; Error: ${deleteResponse._response.bodyAsText}; CV: ${deleteResponse._response.headers.get("MS-CV")}`);
      }
    }
  }
}

main();

Obtener y actualizar brevemente el programa

getUSProgramBrief Use para recuperar un único programa breve por su identificador. Use upsertUSProgramBrief para actualizar un breve programa. upsertUSProgramBrief acepta un ShortCodesUpsertUSProgramBriefOptionalParams objeto , en el que solo es necesario establecer los campos que cambian.

import { ShortCodesClient } from "@azure-tools/communication-short-codes";

const connectionString = "endpoint=<endpoint>;accessKey=<accessKey>";
const client = new ShortCodesClient(connectionString);

async main function() {
  // get a program briefs for a resource
  const programBriefId = process.env.PROGRAM_BRIEF_TO_GET || "<program brief Id>";
  var programBrief = await client.getUSProgramBrief(programBriefId);
  console.log(`Program brief with Id ${programBrief.id} has status ${programBrief.status} which was last updated ${programBrief.statusUpdatedDate}`);

  // update the program brief
  var updateRequest: ShortCodesUpsertUSProgramBriefOptionalParams = {
      body: {
          id: programBriefId,
          programDetails: {
              privacyPolicyUrl: "https://contoso.com/updated-privacy",
              termsOfServiceUrl: "https://contoso.com/updated-terms-of-service"
          }
      }
  };
  var upsertResponse = await client.upsertUSProgramBrief(programBriefId, updateRequest);
  if (upsertResponse._response.status == 200) {
      console.log(`Successfully updated terms of service and privacy policy for program brief ${programBriefId}`);
  } else {
      throw new Error(`Failed to update program brief with Id ${programBriefId}.
      Status code: ${upsertResponse._response.status}; Error: ${upsertResponse._response.bodyAsText}; CV: ${upsertResponse._response.headers.get("MS-CV")}`);
  }
}

main();

Obtener códigos cortos

Use listShortCodes para paginar todos los códigos cortos que pertenecen a un recurso.

import { ShortCodesClient } from "@azure-tools/communication-short-codes";

const connectionString = "endpoint=<endpoint>;accessKey=<accessKey>";
const client = new ShortCodesClient(connectionString);

async main function() {
  // get all short codes for a resource
  var shortCodes = await client.listShortCodes();

  // print all short codes
  for await (const shortCode of shortCodes) {
    console.log(`${shortCode}`);
  }
}

main();

Solución de problemas

Pasos siguientes

Eche un vistazo al directorio de ejemplos para obtener ejemplos detallados sobre cómo usar esta biblioteca.

Contribuciones

Si desea contribuir a esta biblioteca, lea la guía de contribución para obtener más información sobre cómo compilar y probar el código.

Impresiones