Class: Zavudev::Resources::Messages

Inherits:
Object
  • Object
show all
Defined in:
lib/zavudev/resources/messages.rb,
sig/zavudev/resources/messages.rbs

Instance Method Summary collapse

Constructor Details

#initialize(client:) ⇒ Messages

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new instance of Messages.

Parameters:



212
213
214
 
# File 'lib/zavudev/resources/messages.rb', line 212

def initialize(client:)
  @client = client
end

Instance Method Details

#list(channel: nil, cursor: nil, limit: nil, status: nil, to: nil, request_options: {}) ⇒ Zavudev::Internal::Cursor<Zavudev::Models::Message>

List messages previously sent by this project.

Parameters:

Returns:

See Also:



44
45
46
47
48
49
50
51
52
53
54
55
 
# File 'lib/zavudev/resources/messages.rb', line 44

def list(params = {})
  parsed, options = Zavudev::MessageListParams.dump_request(params)
  query = Zavudev::Internal::Util.encode_query_params(parsed)
  @client.request(
    method: :get,
    path: "v1/messages",
    query: query,
    page: Zavudev::Internal::Cursor,
    model: Zavudev::Message,
    options: options
  )
end

#react(message_id, emoji:, zavu_sender: nil, request_options: {}) ⇒ Zavudev::Models::MessageResponse

Some parameter documentations has been truncated, see Models::MessageReactParams for more details.

Send an emoji reaction to an existing WhatsApp message. Reactions are only supported for WhatsApp messages.

Parameters:

  • message_id (String) —

    Path param

  • emoji (String) —

    Body param: Single emoji character to react with.

  • zavu_sender (String) —

    Header param: Optional sender profile ID. If omitted, the project's default send

  • request_options (Zavudev::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



76
77
78
79
80
81
82
83
84
85
86
87
 
# File 'lib/zavudev/resources/messages.rb', line 76

def react(message_id, params)
  parsed, options = Zavudev::MessageReactParams.dump_request(params)
  header_params = {zavu_sender: "zavu-sender"}
  @client.request(
    method: :post,
    path: ["v1/messages/%1$s/reactions", message_id],
    headers: parsed.slice(*header_params.keys).transform_keys(header_params),
    body: parsed.except(*header_params.keys),
    model: Zavudev::MessageResponse,
    options: options
  )
end

#retrieve(message_id, request_options: {}) ⇒ Zavudev::Models::MessageResponse

Get message by ID

Parameters:

Returns:

See Also:



16
17
18
19
20
21
22
23
 
# File 'lib/zavudev/resources/messages.rb', line 16

def retrieve(message_id, params = {})
  @client.request(
    method: :get,
    path: ["v1/messages/%1$s", message_id],
    model: Zavudev::MessageResponse,
    options: params[:request_options]
  )
end

#send_(to:, attachments: nil, channel: nil, content: nil, fallback_enabled: nil, html_body: nil, idempotency_key: nil, message_type: nil, metadata: nil, reply_to: nil, subject: nil, text: nil, voice_language: nil, zavu_sender: nil, request_options: {}) ⇒ Zavudev::Models::MessageResponse

Some parameter documentations has been truncated, see Models::MessageSendParams for more details.

Send a message to a recipient via SMS or WhatsApp.

Channel selection:

  • If channel is omitted and messageType is text, defaults to SMS
  • If messageType is anything other than text, WhatsApp is used automatically

WhatsApp 24-hour window:

  • Free-form messages (non-template) require an open 24h window
  • Window opens when the user messages you first
  • Use template messages to initiate conversations outside the window

Plan allowances and email billing:

  • WhatsApp, Telegram, Instagram and Messenger share an allowance of 2,000 messages per month on Free. Over it, sends return 429 with code a2p_limit_exceeded and upgrade details; the counter resets on the 1st of each month. Paid plans have no message caps
  • Email is billed from your prepaid balance in 1,000-message blocks: $0.40 per 1,000 transactional emails, $0.80 per 1,000 marketing (broadcast) emails. A block is charged when your monthly count crosses each 1,000 boundary, and at zero balance email sends return 402 with code insufficient_balance. Free teams start with $2 of credit and additionally cap at 3,000 emails/month and 100/day. Teams on earlier plans keep their original email quotas instead
  • SMS and voice are billed per message from your balance on every plan

Email recipient pre-flight: Email messages are validated automatically before dispatch. Sends that would be a guaranteed hard bounce are failed instead of sent, protecting your bounce rate: the message transitions to failed (visible via GET /v1/messages/{messageId} and the message.failed webhook) with errorCode set to EMAIL_INVALID_RECIPIENT (malformed address), EMAIL_DOMAIN_NOT_FOUND (recipient domain has no MX or A records), or EMAIL_RECIPIENT_SUPPRESSED (address is on your suppression list after a previous bounce or complaint). Advisory signals (role addresses, disposable domains) do not block sends — check them beforehand with POST /v1/introspect/email.

Parameters:

  • to (String) —

    Body param: Recipient phone number in E.164 format, email address, WhatsApp busi

  • attachments (Array<Zavudev::Models::MessageSendParams::Attachment>) —

    Body param: Email attachments. Only supported when channel is 'email'. Maximum 4

  • channel (Symbol, Zavudev::Models::Channel) —

    Body param: Delivery channel. Use 'auto' for intelligent routing. If omitted, ch

  • content (Zavudev::Models::MessageContent) —

    Body param: Additional content for non-text message types.

  • fallback_enabled (Boolean) —

    Body param: Whether to enable automatic fallback to SMS if WhatsApp fails. Defau

  • html_body (String) —

    Body param: HTML body for email messages. If provided, email will be sent as mul

  • idempotency_key (String) —

    Body param: Optional idempotency key to avoid duplicate sends.

  • message_type (Symbol, Zavudev::Models::MessageType) —

    Body param: Type of message. Defaults to 'text'.

  • metadata (Hash{Symbol=>String}) —

    Body param: Arbitrary metadata to associate with the message.

  • reply_to (String) —

    Body param: Reply-To email address for email messages.

  • subject (String) —

    Body param: Email subject line. Required when channel is 'email' or recipient is

  • text (String) —

    Body param: Text body for text messages or caption for media messages.

  • voice_language (String) —

    Body param: Language code for voice text-to-speech (e.g., 'en-US', 'es-ES', 'pt-

  • zavu_sender (String) —

    Header param: Optional sender profile ID. If omitted, the project's default send

  • request_options (Zavudev::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



165
166
167
168
169
170
171
172
173
174
175
176
 
# File 'lib/zavudev/resources/messages.rb', line 165

def send_(params)
  parsed, options = Zavudev::MessageSendParams.dump_request(params)
  header_params = {zavu_sender: "zavu-sender"}
  @client.request(
    method: :post,
    path: "v1/messages",
    headers: parsed.slice(*header_params.keys).transform_keys(header_params),
    body: parsed.except(*header_params.keys),
    model: Zavudev::MessageResponse,
    options: options
  )
end

#show_typing(message_id, zavu_sender: nil, request_options: {}) ⇒ Zavudev::Models::MessageShowTypingResponse

Some parameter documentations has been truncated, see Models::MessageShowTypingParams for more details.

Mark an inbound WhatsApp message as read and display a typing indicator to the user while you prepare a response. The indicator is automatically dismissed when you send a reply, or after 25 seconds — whichever comes first. Only valid for inbound WhatsApp messages. Use this when a reply will take more than a couple of seconds (LLM agent, tool call, lookup) to improve the recipient's experience.

Parameters:

  • message_id (String)
  • zavu_sender (String) —

    Optional sender profile ID. If omitted, the project's default sender will be use

  • request_options (Zavudev::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



198
199
200
201
202
203
204
205
206
207
 
# File 'lib/zavudev/resources/messages.rb', line 198

def show_typing(message_id, params = {})
  parsed, options = Zavudev::MessageShowTypingParams.dump_request(params)
  @client.request(
    method: :post,
    path: ["v1/messages/%1$s/typing", message_id],
    headers: parsed.transform_keys(zavu_sender: "zavu-sender"),
    model: Zavudev::Models::MessageShowTypingResponse,
    options: options
  )
end