cmdotcom/text-sdk-php

使用 CM.com 发送消息的 PHP SDK

2.3.1 2024-06-21 14:48 UTC

README

GitHub Workflow codecov Packagist

CM 文本 SDK

一个软件开发工具包,提供与 CM.com 文本服务交互的方式。使用的 API

要求

  • php 7.* 或 8.0 或 8.1 或 8.2 或 8.3

使用方法

实例化客户端

使用您的唯一 ApiKey(或产品令牌),该令牌授权您在 CM 平台上。始终保密此密钥!

产品令牌可以在平台上的 通道 应用中的 网关 部分找到。

$client = new \CMText\TextClient('your-api-key');

发送消息

通过调用 SendMessage 并提供消息文本、发送者名称、接收者电话号码和参考(可选)来实现。

$result = $client->SendMessage('Message_Text', 'CM.com', [ 'Recipient_PhoneNumber' ], 'Your_Reference');

获取结果

SendMessagesend 返回一个类型为 TextClientResult 的对象,例如

{
  "statusMessage": "Created 1 message(s)",
  "statusCode": 201,
  "details": [
    {
      "reference": "Example_Reference",
      "status": "Accepted",
      "to": "Example_PhoneNumber",
      "parts": 1,
      "details": null
    },
    {
      "reference": "Example_Reference2",
      "status": "Rejected",
      "to": "Example_PhoneNumber2",
      "parts": 0,
      "details": "A body without content was found"
    }
  ]
}

状态码

有关所有可能返回的状态码,请参考 TextClientStatusCodes 类。

发送富媒体消息

通过使用 Message 类,可以为 WhatsApp 和 RCS 等渠道创建包含媒体的消息。

$client = new TextClient('your-api-key');
$message = new Message('Message Text', 'Sender_name', ['Recipient_PhoneNumber']);
$message
    ->WithChannels([Channels::WHATSAPP])
    ->WithHybridAppKey('your-secret-hybrid-app-key')
    ->WithRichMessage(
        new MediaMessage(
            'cm.com',
            'https://avatars3.githubusercontent.com/u/8234794?s=200&v=4',
            'image/png'
        )
    )
    ->WithSuggestions([
        new ReplySuggestion('Opt In', 'OK'),
        new ReplySuggestion('Opt Out', 'STOP'),
    ]);
$result = $client->send( [$message] );

发送 WhatsApp 模板消息

通过使用 Message 类,可以创建模板消息。请注意,这仅适用于 WhatsApp,并且在发送之前需要批准模板。有关更多信息,请参阅我们的文档:https://www.cm.com/en-en/app/docs/api/business-messaging-api/1.0/index#whatsapp-template-message

$client = new TextClient('your-api-key');
$message = new Message('Message Text', 'Sender_name', ['Recipient_PhoneNumber']);
$message
    ->WithChannels([Channels::WHATSAPP])
    ->WithTemplate(
            new TemplateMessage(
                new WhatsappTemplate(
                    'namespace',
                    'elementname',
                    new Language('en'),
                    [
                        new ComponentBody([
                            new ComponentParameterText('firstname')
                        ])
                    ]
                )
            )
    );
$result = $client->send( [$message] );

发送富 WhatsApp 模板消息

还可以发送包含图像的丰富模板!

$client = new TextClient('your-api-key');
$message = new Message('Message Text', 'Sender_name', ['Recipient_PhoneNumber']);
$message
    ->WithChannels([Channels::WHATSAPP])
    ->WithTemplate(
        new TemplateMessage(
            new WhatsappTemplate(
                'template-name',
                'the-namespace-of-template',
                new Language('en'),
                [
                    new ComponentHeader([
                        new ComponentParameterImage(
                            new MediaContent(
                                'image name',
                                'https://image.location',
                                'image/png'
                            )
                        )
                    ]),
                    new ComponentBody([
                        new ComponentParameterText('firstname')
                    ])
                ]
            )
        )
    );
$result = $client->send( [$message] );

发送 Apple Pay 请求

现在可以在 Apple Business Chat 中发送仅限 Apple Pay 的请求!

$client = new TextClient('your-api-key');
$message = new Message('Message Text', 'Sender_name', ['Recipient_PhoneNumber']);
$message
    ->WithChannels([Channels::IMESSAGE])
    ->WithPayment(
        new PaymentMessage(
            new ApplePayConfiguration(
                'merchant-name',
                'product-description',
                'unique-order-guid',
                1,
                'currency-code',
                'recipient-email',
                'recipient-country-code',
                'language-country-code',
                true,
                true,
                [
                    new LineItem(
                        'product-name',
                        'final-or-pending',
                        1
                    )
                ]
            )
        )
    );
$result = $client->send( [$message] );

发送 WhatsApp 交互式消息

现在可以在不使用模板的情况下发送 WhatsApp 中仅支持的消息列表和回复按钮。

$client = new TextClient('your-api-key');
$message = new Message('Message Text', 'Sender_name', ['Recipient_PhoneNumber']);
$message
    ->WithChannels([Channels::WHATSAPP])
    ->WithRichMessage(
        new WhatsAppInteractiveMessage(
            new WhatsAppInteractiveContent(
                WhatsAppInteractiveContentTypes::LIST,
                new WhatsAppInteractiveHeader(
                    WhatsAppInteractiveHeaderTypes::TEXT,
                    'List message example'
                ),
                new WhatsAppInteractiveBody('checkout our list message demo'),
                new WhatsAppInteractiveListAction(
                    'Descriptive list title',
                    [new WhatsAppInteractiveSection(
                        'Select an option',
                        [new WhatsAppInteractiveSectionRow(
                            'unique title 1',
                            rand(),
                            'description text'
                        ),new WhatsAppInteractiveSectionRow(
                            'unique title 2',
                            rand()
                        )]
                    )]
                ),
                new WhatsAppInteractiveFooter('footer text')
            )
        )
    );
$result = $client->send( [$message] );

仅通过回复按钮,您可以发送图像、视频或文档等媒体。以下是一个示例。

$client = new TextClient('your-api-key');
$message = new Message('Message Text', 'Sender_name', ['Recipient_PhoneNumber']);
$message
    ->WithChannels([Channels::WHATSAPP])
    ->WithRichMessage(
        new WhatsAppInteractiveMessage(
            new WhatsAppInteractiveContent(
                WhatsAppInteractiveContentTypes::BUTTON,
                new WhatsAppInteractiveHeader(
                    WhatsAppInteractiveHeaderTypes::IMAGE,
                    null,
                    new MediaContent(
                        'media name',
                        'media.url',
                        'mime/type'
                    )
                ),
                new WhatsAppInteractiveBody('checkout our list message demo'),
                new WhatsAppInteractiveButtonAction(
                    [new WhatsAppInteractiveReplyButton(
                        'button 1 reply-text',
                        rand()
                    ),new WhatsAppInteractiveReplyButton(
                        'button 2 title',
                        rand()
                    )]
                ),
                new WhatsAppInteractiveFooter('footer text')
            )
        )
    );
$result = $client->send( [$message] );