Ir para o conteúdo
Pipefácil

Enviar mensagem

Ver como MarkdownConfigurar agente
POST/api/v1/conversations/messages

Envia uma mensagem de WhatsApp pelo workspace da chave, com autoria do membro que a criou, e retorna a mensagem salva. type assume text por padrão. Informe channelId ou senderPhoneNumberId para escolher o canal; sem eles, usa o canal padrão do workspace. O caminho legado POST /api/v1/messages mantém o mesmo contrato e os mesmos requisitos. Novas integrações devem usar /api/v1/conversations/messages.

Exemplos

A URL usa o servidor de produção. Defina PIPEFACIL_API_KEY e as variáveis de caminho (como SEQ ou ID) com os identificadores reais. Ajuste o corpo antes de executar: requisições de escrita alteram dados do workspace.

cURL

curl --request POST \
  --url "https://pipefacil-server.matchsales.com.br/api/v1/conversations/messages" \
  --header "Authorization: Bearer $PIPEFACIL_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "to": "5511999999999",
  "type": "text",
  "text": "Olá, Ana. Podemos conversar sobre a proposta?",
  "channelId": "ID_DO_CANAL"
}'
JavaScript
const response = await fetch(`https://pipefacil-server.matchsales.com.br/api/v1/conversations/messages`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PIPEFACIL_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "to": "5511999999999",
  "type": "text",
  "text": "Olá, Ana. Podemos conversar sobre a proposta?",
  "channelId": "ID_DO_CANAL"
}),
});

if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const text = await response.text();
const data = text ? JSON.parse(text) : null;
Python
import os
import json
import requests

response = requests.request(
    "POST",
    f"https://pipefacil-server.matchsales.com.br/api/v1/conversations/messages",
    headers={"Authorization": f"Bearer {os.environ['PIPEFACIL_API_KEY']}"},
    json=json.loads("{\n  \"to\": \"5511999999999\",\n  \"type\": \"text\",\n  \"text\": \"Olá, Ana. Podemos conversar sobre a proposta?\",\n  \"channelId\": \"ID_DO_CANAL\"\n}"),
)
response.raise_for_status()
data = response.json() if response.content else None

Corpo da requisição

Content-Type: application/json · obrigatório

{
  "to": "5511999999999",
  "type": "text",
  "text": "Olá, Ana. Podemos conversar sobre a proposta?",
  "channelId": "ID_DO_CANAL"
}
CampoTipoObrigatório no objetoDescrição
tostringSimTelefone do destinatário em E.164 ou no formato normalizado do workspace.
typestringNãotext, image, audio, video, document, template, … Aceita null.
textstringNãoAceita null.
senderPhoneNumberIdstringNãoIdentificador do número de telefone do canal no provedor. Aceita null.
channelIdstringNãoIdentificador do canal de envio; tem prioridade sobre senderPhoneNumberId. Aceita null.
mediaAssetIdstringNãoIdentificador de mídia já armazenada no workspace. Aceita null.
mediaLinkstringNãoURL pública usada pelo provedor para baixar a mídia. Aceita null.
captionstringNãoAceita null.
filenamestringNãoAceita null.
mimeTypestringNãoAceita null.
templateNamestringNãoAceita null.
templateLanguageCodestringNãoAceita null.
templateComponentsarrayNãoAceita null.
quotedMessageIdstringNãoMensagem à qual se está respondendo. Aceita null.
voicebooleanNãoSomente áudio. Padrão: true, para entregar como mensagem de voz (ícone de microfone e forma de onda). Envie false para entregar como arquivo de áudio. Aceita null.
Esquema OpenAPI
{
  "type": "object",
  "required": [
    "to"
  ],
  "properties": {
    "to": {
      "type": "string",
      "description": "Telefone do destinatário em E.164 ou no formato normalizado do workspace."
    },
    "type": {
      "type": "string",
      "default": "text",
      "description": "text, image, audio, video, document, template, …",
      "nullable": true
    },
    "text": {
      "type": "string",
      "nullable": true
    },
    "senderPhoneNumberId": {
      "type": "string",
      "nullable": true,
      "description": "Identificador do número de telefone do canal no provedor."
    },
    "channelId": {
      "type": "string",
      "nullable": true,
      "description": "Identificador do canal de envio; tem prioridade sobre senderPhoneNumberId."
    },
    "mediaAssetId": {
      "type": "string",
      "nullable": true,
      "description": "Identificador de mídia já armazenada no workspace."
    },
    "mediaLink": {
      "type": "string",
      "nullable": true,
      "description": "URL pública usada pelo provedor para baixar a mídia."
    },
    "caption": {
      "type": "string",
      "nullable": true
    },
    "filename": {
      "type": "string",
      "nullable": true
    },
    "mimeType": {
      "type": "string",
      "nullable": true
    },
    "templateName": {
      "type": "string",
      "nullable": true
    },
    "templateLanguageCode": {
      "type": "string",
      "nullable": true
    },
    "templateComponents": {
      "type": "array",
      "nullable": true,
      "items": {
        "type": "object",
        "additionalProperties": true
      }
    },
    "quotedMessageId": {
      "type": "string",
      "nullable": true,
      "description": "Mensagem à qual se está respondendo."
    },
    "voice": {
      "type": "boolean",
      "nullable": true,
      "description": "Somente áudio. Padrão: true, para entregar como mensagem de voz (ícone de microfone e forma de onda). Envie false para entregar como arquivo de áudio."
    }
  },
  "example": {
    "to": "5511999999999",
    "type": "text",
    "text": "Olá, Ana. Podemos conversar sobre a proposta?",
    "channelId": "ID_DO_CANAL"
  }
}

Respostas

201Criado
CampoTipoDescrição
dataSendMessageResponse—
data.idstring—
data.conversationIdstring—
data.channelIdstring—
data.externalIdstringIdentificador da mensagem no provedor; nulo até a aceitação pelo provedor. Aceita null.
data.directionstringValores: inbound, outbound.
data.typestring—
data.statusstring—
data.bodystring—
data.errorMessagestringAceita null.
data.timestampstringFormato: date-time.
messagestring—
Esquema OpenAPI
{
  "type": "object",
  "properties": {
    "data": {
      "$ref": "#/components/schemas/SendMessageResponse"
    },
    "message": {
      "type": "string"
    }
  }
}
400Falha de validação dos campos; `fieldErrors` contém os erros.
CampoTipoDescrição
errorstring—
codestringValores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE.
requestIdstring—
detailsstringAceita null.
fieldErrorsarrayAceita null.
fieldErrors[].fieldstring—
fieldErrors[].messagestring—
Esquema OpenAPI
{
  "type": "object",
  "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.",
  "properties": {
    "error": {
      "type": "string"
    },
    "code": {
      "type": "string",
      "enum": [
        "BAD_REQUEST",
        "VALIDATION_ERROR",
        "UNAUTHORIZED",
        "FORBIDDEN",
        "FEATURE_DISABLED",
        "NOT_FOUND",
        "CONFLICT",
        "QUOTA_EXCEEDED",
        "UNPROCESSABLE_ENTITY",
        "INTERNAL_ERROR",
        "SERVICE_UNAVAILABLE"
      ]
    },
    "requestId": {
      "type": "string"
    },
    "details": {
      "type": "string",
      "nullable": true
    },
    "fieldErrors": {
      "type": "array",
      "nullable": true,
      "items": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  },
  "required": [
    "error",
    "code",
    "requestId"
  ]
}
401Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo.
CampoTipoDescrição
errorstring—
codestringValores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE.
requestIdstring—
detailsstringAceita null.
fieldErrorsarrayAceita null.
fieldErrors[].fieldstring—
fieldErrors[].messagestring—
Esquema OpenAPI
{
  "type": "object",
  "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.",
  "properties": {
    "error": {
      "type": "string"
    },
    "code": {
      "type": "string",
      "enum": [
        "BAD_REQUEST",
        "VALIDATION_ERROR",
        "UNAUTHORIZED",
        "FORBIDDEN",
        "FEATURE_DISABLED",
        "NOT_FOUND",
        "CONFLICT",
        "QUOTA_EXCEEDED",
        "UNPROCESSABLE_ENTITY",
        "INTERNAL_ERROR",
        "SERVICE_UNAVAILABLE"
      ]
    },
    "requestId": {
      "type": "string"
    },
    "details": {
      "type": "string",
      "nullable": true
    },
    "fieldErrors": {
      "type": "array",
      "nullable": true,
      "items": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  },
  "required": [
    "error",
    "code",
    "requestId"
  ]
}
403Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida.
CampoTipoDescrição
errorstring—
codestringValores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE.
requestIdstring—
detailsstringAceita null.
fieldErrorsarrayAceita null.
fieldErrors[].fieldstring—
fieldErrors[].messagestring—
Esquema OpenAPI
{
  "type": "object",
  "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.",
  "properties": {
    "error": {
      "type": "string"
    },
    "code": {
      "type": "string",
      "enum": [
        "BAD_REQUEST",
        "VALIDATION_ERROR",
        "UNAUTHORIZED",
        "FORBIDDEN",
        "FEATURE_DISABLED",
        "NOT_FOUND",
        "CONFLICT",
        "QUOTA_EXCEEDED",
        "UNPROCESSABLE_ENTITY",
        "INTERNAL_ERROR",
        "SERVICE_UNAVAILABLE"
      ]
    },
    "requestId": {
      "type": "string"
    },
    "details": {
      "type": "string",
      "nullable": true
    },
    "fieldErrors": {
      "type": "array",
      "nullable": true,
      "items": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  },
  "required": [
    "error",
    "code",
    "requestId"
  ]
}
404Recurso não encontrado ou fora da visibilidade do membro.
CampoTipoDescrição
errorstring—
codestringValores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE.
requestIdstring—
detailsstringAceita null.
fieldErrorsarrayAceita null.
fieldErrors[].fieldstring—
fieldErrors[].messagestring—
Esquema OpenAPI
{
  "type": "object",
  "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.",
  "properties": {
    "error": {
      "type": "string"
    },
    "code": {
      "type": "string",
      "enum": [
        "BAD_REQUEST",
        "VALIDATION_ERROR",
        "UNAUTHORIZED",
        "FORBIDDEN",
        "FEATURE_DISABLED",
        "NOT_FOUND",
        "CONFLICT",
        "QUOTA_EXCEEDED",
        "UNPROCESSABLE_ENTITY",
        "INTERNAL_ERROR",
        "SERVICE_UNAVAILABLE"
      ]
    },
    "requestId": {
      "type": "string"
    },
    "details": {
      "type": "string",
      "nullable": true
    },
    "fieldErrors": {
      "type": "array",
      "nullable": true,
      "items": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  },
  "required": [
    "error",
    "code",
    "requestId"
  ]
}
429Limite de requisições excedido por workspace ou IP.
CampoTipoDescrição
errorstring—
codestringValores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE.
requestIdstring—
detailsstringAceita null.
fieldErrorsarrayAceita null.
fieldErrors[].fieldstring—
fieldErrors[].messagestring—
Esquema OpenAPI
{
  "type": "object",
  "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.",
  "properties": {
    "error": {
      "type": "string"
    },
    "code": {
      "type": "string",
      "enum": [
        "BAD_REQUEST",
        "VALIDATION_ERROR",
        "UNAUTHORIZED",
        "FORBIDDEN",
        "FEATURE_DISABLED",
        "NOT_FOUND",
        "CONFLICT",
        "QUOTA_EXCEEDED",
        "UNPROCESSABLE_ENTITY",
        "INTERNAL_ERROR",
        "SERVICE_UNAVAILABLE"
      ]
    },
    "requestId": {
      "type": "string"
    },
    "details": {
      "type": "string",
      "nullable": true
    },
    "fieldErrors": {
      "type": "array",
      "nullable": true,
      "items": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  },
  "required": [
    "error",
    "code",
    "requestId"
  ]
}
OpenAPI JSONMarkdown desta operação

Precisa de ajuda?

Encontrou um problema ou ficou com uma dúvida? Fale com a equipe pelo WhatsApp.

Chamar no WhatsApp
Pipefácil